Translation center API

« Back to API docs

Translate

Endpoints

Getting a translation done via the API involves these steps:

  1. Send text to be translated and create a translation "work order".
  2. Receive a "push" notification when the work is complete, and/or poll for completed orders.
  3. Download the translated documents.
  4. Accept or reject the translation.

Send text or documents to be translated

POST /documents uploads a text string or file. The request body should be a multipart/form-data message, with a document field specifying the document to upload, either as a file or as a plain-text string. Make sure to set the Content-Type in the payload.

When sending the content as a string, you can optionally specify the name of the file in a name parameter.

When the upload is successful, you'll get a 201 Created response, along with the JSON representation of the new document. Save the document_id from this response, to attach to the order you create in the next step.

Example of sending plain-text with Curl:

curl -H 'X-Proz-API-Key: {YOUR_API_KEY}' \
    --form document="Here is some text to be translated." \
    --form name=myfile.txt \
    https://twb.translationcenter.org/api/v1/documents

Example of uploading a file with Curl:

curl -H 'X-Proz-API-Key: {YOUR_API_KEY}' \
    --form document=@testfile.txt \
    https://twb.translationcenter.org/api/v1/documents

Example response:

{
    "document_id": 12345,
    "name": "testfile.txt",
    "self_link": "https://twb.translationcenter.org/api/v1/documents/12345",
    "download_link": "https://twb.translationcenter.org/api/v1/document/12345/file"
}

Create a translation work order

POST /orders will create a new order from the given parameters. It will return 201 Created, and a JSON data structure with a link to view the order on the web. Visit this link to communicate with the translators, etc.

Example request with Curl:

curl -H 'X-Proz-API-Key: {YOUR_API_KEY}' \
    -H 'Content-Type: application/json' \
    -d '{
            "contact_email": "test@example.com",
            "title": "Test title",
            "source_lang": "eng",
            "target_langs": ["fra", "esl"],
            "source_document_ids": [12345],
            "source_wordcount": 321,
            "instructions": "Sample instructions for this job.",
            "deadline": "2015-01-01 00:00:00",
            "urgency": "high",
            "project_id": 509,
            "callback_url": "https://www.example.com/my-callback-url"
    }' \
    https://twb.translationcenter.org/api/v1/orders

The deadline must be in the UTC time zone, in the format YYYY-MM-DD HH:MM:SS.

urgency can optionally be specified to give translators additional information about how to prioritize this job. Allowed values are high, low, or normal.

Optionally specify a project_id if the order is part of a pre-configured project, with existing translation teams and resources. See GET /projects to get a list of the project IDs you can specify here.

It's possible to omit the source documents, and instead specify instructions to be shown to the translator after accepting the job, with information about how to access the source documents elsewhere (such as on an external translation platform). Use the post_assign_instructions field for this.

curl -H 'X-Proz-API-Key: {YOUR_API_KEY}' \
    -H 'Content-Type: application/json' \
    -d '{
            "contact_email": "test@example.com",
            "source_lang": "eng",
            "target_langs": ["fra"],
            "source_wordcount": 321,
            "instructions": "Sample instructions for this job.",
            "urgency": "high",
            "post_assign_instructions": "Go to https://example.com/xyz-123-abc to work on this job."
    }' \
    https://twb.translationcenter.org/api/v1/orders

Example response:

{
    "order_id": 11400,
    "order_web_url": "https://twb.translationcenter.org/workspace/client-workorders/view/id/11400"
}

Receive a "push" notification when the work is complete

When the work is complete, a POST request will be sent to the callback_url you specified when creating the order. (It's also possible to poll for completed orders.)

Example push notification:
{
    "event": "job:completed",
    "event_data": {
        "order_id":11400,
        "order_web_url":"https://twb.translationcenter.org/workspace/client-workorders/view/id/11400"
        "job_id":17001,
        "job_web_url":"https://twb.translationcenter.org/workspace/jobs/view/id/17001",
        "delivered_documents": [
            {
                "document_id": 12345,
                "download_url": "https://twb.translationcenter.org/api/v1/document/12345/file"
            }
        ]
    }
}

You can download the completed documents from the links provided.

Poll for completed orders

It's also possible to poll for completed orders, instead of or in addition to receiving a push notification when the work is complete.

GET /orders?delivery_status=to_accept will return a collection of orders with delivered documents that you have not yet accepted or rejected. See GET /orders for details.

Download documents

GET /document/{id}/file downloads a document as a file. Check the response headers for the file name and type.

Example request with Curl:

curl -JO -H "X-Proz-API-Key: {YOUR_API_KEY}" 'https://twb.translationcenter.org/api/v1/document/12345/file'

Example response:

Content-Disposition: attachment; filename="test-part-1-fr.txt"
Content-Length: 3683
Content-Transfer-Encoding: binary
Content-Type: text/plain; charset=us-ascii

{binary file data}

curl: Saved to filename 'test-part-1-fr.txt'

Accept or reject the completed work

Once you have downloaded the completed translation, mark it as accepted so you can exclude it from your polling results, or reject it so the work can be corrected. See PATCH /orders/:id/delivered_documents/:doc_id for details.

Endpoints

Documents

Create documents

POST /documents uploads a text string or file. The request body should be a multipart/form-data message, with a document field specifying the document to upload, either as a file or as a plain-text string. Make sure to set the Content-Type in the payload.

When sending the content as a string, you can optionally specify the name of the file in a name parameter.

When the upload is successful, you'll get a 201 Created response, along with the JSON representation of the new document. Save the document_id from this response, to attach to the order you create in the next step.

Example of sending plain-text with Curl:

curl -H 'X-Proz-API-Key: {YOUR_API_KEY}' \
    --form document="Here is some text to be translated." \
    --form name=myfile.txt \
    https://twb.translationcenter.org/api/v1/documents

Example of uploading a file with Curl:

curl -H 'X-Proz-API-Key: {YOUR_API_KEY}' \
    --form document=@testfile.txt \
    https://twb.translationcenter.org/api/v1/documents

Example response:

{
    "document_id": 12345,
    "name": "testfile.txt",
    "self_link": "https://twb.translationcenter.org/api/v1/documents/12345",
    "download_link": "https://twb.translationcenter.org/api/v1/document/12345/file"
}

Get a document

GET /documents/{id} gets a information about a document. (To download the document itself, see downloading documents, below.)

Example request with Curl:

curl -H "X-Proz-API-Key: {YOUR_API_KEY}" 'https://twb.translationcenter.org/api/v1/documents/12345'

Example response:

{
    "document_id": 12345,
    "name": "test-part-1-fr.txt",
    "self_link": "https://twb.translationcenter.org/api/v1/documents/12345",
    "download_link": "https://twb.translationcenter.org/api/v1/document/12345/file"
}

Download a document as a file

GET /document/{id}/file downloads a document as a file. Check the response headers for the file name and type.

Example request with Curl:

curl -JO -H "X-Proz-API-Key: {YOUR_API_KEY}" 'https://twb.translationcenter.org/api/v1/document/12345/file'

Example response:

Content-Disposition: attachment; filename="test-part-1-fr.txt"
Content-Length: 3683
Content-Transfer-Encoding: binary
Content-Type: text/plain; charset=us-ascii

{binary file data}

curl: Saved to filename 'test-part-1-fr.txt'

Orders

Translation work is initiated with an "order" (also known as a "work order") from a "client". The order is broken out into one or more "jobs", with one job for each target language.

Create orders

POST /orders will create a new order from the given parameters. It will return 201 Created, with the current JSON representation of the order if the creation was a success. See the GET /orders/:id endpoint for details. If the user does not have access to create new orders a 403 Forbidden will be returned.

Example request with Curl:

curl -H 'X-Proz-API-Key: {YOUR_API_KEY}' \
    -H 'Content-Type: application/json' \
    -d '{
            "contact_email": "test@example.com",
            "title": "Test title",
            "source_lang": "eng",
            "target_langs": ["fra", "esl"],
            "source_document_ids": [12345],
            "source_wordcount": 321,
            "instructions": "Sample instructions for this job.",
            "deadline": "2015-01-01 00:00:00",
            "urgency": "high",
            "project_id": 509,
            "callback_url": "https://www.example.com/my-callback-url"
    }' \
    https://twb.translationcenter.org/api/v1/orders

The deadline must be in the UTC time zone, in the format YYYY-MM-DD HH:MM:SS.

urgency can optionally be specified to give translators additional information about how to prioritize this job. Allowed values are high, low, or normal.

Optionally specify a project_id if the order is part of a pre-configured project, with existing translation teams and resources. See GET /projects to get a list of the project IDs you can specify here.

It's possible to omit the source documents, and instead specify instructions to be shown to the translator after accepting the job, with information about how to access the source documents elsewhere (such as on an external translation platform). Use the post_assign_instructions field for this.

curl -H 'X-Proz-API-Key: {YOUR_API_KEY}' \
    -H 'Content-Type: application/json' \
    -d '{
            "contact_email": "test@example.com",
            "source_lang": "eng",
            "target_langs": ["fra"],
            "source_wordcount": 321,
            "instructions": "Sample instructions for this job.",
            "urgency": "high",
            "post_assign_instructions": "Go to https://example.com/xyz-123-abc to work on this job."
    }' \
    https://twb.translationcenter.org/api/v1/orders

Example response:

{
    "order_id": 11400,
    "order_web_url": "https://twb.translationcenter.org/workspace/client-workorders/view/id/11400"
}

Get an order

GET /orders/:id will return the specified order. If the user does not have access to see the order 403 Forbidden will be returned.

Example request with Curl:

curl -H "X-Proz-API-Key: {YOUR_API_KEY}" 'https://twb.translationcenter.org/api/v1/order/24881'

Example response:

{
    "order_id": 24881,
    "self_link": "https:\/\/twb.translationcenter.org\/api\/v1\/orders\/24881",
    "order_web_url": "https:\/\/twb.translationcenter.org\/workspace\/client-workorders\/view\/id\/24881",
    "status": "delivered",
    "project_id": 0,
    "client_id": 1211,
    "orderer_contact_email": "test@example.com",
    "orderer_account_id": 13040,
    "client_contact_account_id": 13040,
    "pm_account_id": 0,
    "title": "Test title",
    "source_lang": "und",
    "source_wordcount": 243,
    "instructions": "",
    "deadline": "2015-03-01 00:00:00",
    "delivered_documents": [
        {
            "document_id": 122897,
            "attachment_id": 326357,
            "download_link": "https:\/\/twb.translationcenter.org\/api\/v1\/document\/122897\/file",
            "name": "test.txt",
            "self_link": "https:\/\/twb.translationcenter.org\/api\/v1\/orders\/24881\/delivered_documents\/326357",
            "language": "eng",
            "delivery_status": "to_accept"
        }
    ]
}

Get orders

GET /orders will return a collection of the orders that you have access to.

To filter the orders by delivery status, pass a delivery_status parameter with a value of to_accept (to get just the orders with delivered documents you haven't accepted or rejected yet), accepted, or rejected.

Example request with Curl:

curl -H "X-Proz-API-Key: {YOUR_API_KEY}" 'https://twb.translationcenter.org/api/v1/orders'

Example response:

{
"_links": {
    "self": {
        "href": "https:\/\/twb.translationcenter.org\/api\/v1\/orders"
    },
    "next": {
        "href": "https:\/\/twb.translationcenter.org\/api\/v1\/orders?page=2"
    },
    "prev": {
        "href": null
    }
},
"data": [
    {
        "order_id": 25774,
        "self_link": "https:\/\/twb.translationcenter.org\/api\/v1\/orders\/25774",
        "order_web_url": "https:\/\/twb.translationcenter.org\/workspace\/client-workorders\/view\/id\/25774",
        "status": "draft",
        "project_id": 5681,
        "client_id": 1211,
        "orderer_contact_email": "test@test.com",
        "orderer_account_id": 13040,
        "client_contact_account_id": 13040,
        "pm_account_id": 0,
        "title": "Translation Request from twb",
        "source_lang": "eng",
        "source_wordcount": 100,
        "instructions": "Please translate according to ...",
        "deadline": "2015-03-29 07:46:10",
        "delivered_documents": [ ]
    },
    {
        "order_id": 24881,
        "self_link": "https:\/\/twb.translationcenter.org\/api\/v1\/orders\/24881",
        "order_web_url": "https:\/\/twb.translationcenter.org\/workspace\/client-workorders\/view\/id\/24881",
        "status": "delivered",
        "project_id": 0,
        "client_id": 1211,
        "orderer_contact_email": "test@example.com",
        "orderer_account_id": 13040,
        "client_contact_account_id": 13040,
        "pm_account_id": 0,
        "title": "Test title",
        "source_lang": "und",
        "source_wordcount": 234,
        "instructions": "",
        "deadline": "2015-03-01 00:00:00",
        "delivered_documents": [
            {
                "document_id": 122897,
                "attachment_id": 326357,
                "download_link": "https:\/\/twb.translationcenter.org\/api\/v1\/document\/122897\/file",
                "name": "test-6-words.txt",
                "self_link": "https:\/\/twb.translationcenter.org\/api\/v1\/orders\/24881\/delivered_documents\/326357",
                "language": "eng",
                "delivery_status": "to_accept"
            }
        ]
    }
]

Accept or reject delivered documents

To accept or reject a delivered document, send a PATCH request to the self_link property of the delivered document. Set the Content-Type to application/json, and send a JSON payload with the following properties:

  • delivery_status - either "accepted" or "rejected".
  • reject_reason - a string explaining why the delivered document is being rejected. Required if delivery_status is "rejected".

Example request with Curl:

curl -H 'X-Proz-API-Key: {YOUR_API_KEY}' \
    -H 'Content-Type: application/json' \
    --request PATCH \
    -d '{ "delivery_status": "accepted" }' \
    https://twb.translationcenter.org/api/v1/orders/24881/delivered_documents/326357  # The delivered document's self_link

Trouble using the PATCH method?

If your client library doesn't support the PATCH method, you can send a POST request instead, as long as you include an X-HTTP-Method-Override header set to PATCH.

Projects

Orders can be grouped into projects, so they can use project-specific translation teams and resources. Projects are associated with a "client" (the organization requesting the translation work to be done).

Get projects

GET /projects gets a list of projects for a given client. Specify the client ID in the client parameter. Use client=me to get projects for the main client associated with your account.

If the client parameter is invalid, a 400 Bad Request response will be returned. If you specify the ID of a client that you don't have access to, a 403 Forbidden response will be returned.

Example request with Curl:

curl -H "X-Proz-API-Key: {YOUR_API_KEY}" 'https://twb.translationcenter.org/api/v1/projects?client=me'

Example response:

[
    {
        "project_id": 502,
        "client_id": 929,
        "name": "Nigerian Elections Project",
        "summary": "Translation of crisis reports for Nigerian election monitors.",
        "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse ornare purus eros, sit amet hendrerit ante consectetur tempor. Suspendisse faucibus tempus arcu ac molestie. Vestibulum posuere eleifend quam, sed fringilla augue ullamcorper in. Nulla tincidunt nisi orci, nec gravida sapien dapibus dictum. Vestibulum gravida ut metus sit amet gravida. In feugiat nulla vel neque placerat tristique. Aenean iaculis eu ipsum non finibus. Aliquam diam turpis, viverra eget tincidunt quis, semper vitae ipsum. Nulla pellentesque ac nisl feugiat pretium."
    }
]

« Back to API docs