Translate document

Use this call to translate a document from the given source language to the defined target language.

Tip: Before sending the document

• Run the GET /v2/languages/document-translation endpoint to check the selected source/target language is supported.
  
• Pay special attention to the direction (source-target) of the language pair codes.
  
• Check the Documents management guide for restrictions and recommendations.
  

This is an asynchronous operation. Upon a successful request, the API returns a jobId which you can use to track the translation's progress and retrieve the result. There are two ways to get the result of the translation:

1. Webhook Callbacks (Recommended)

You can provide a successCallbackUrl and/or an errorCallbackUrl in your request. Our system will send a POST request to the appropriate URL once the translation is completed or if it fails. This is the most efficient method as it avoids unnecessary polling.

Refer to the callbacks guide for more details.

2. Polling

If you can not use webhooks, you can periodically check the translation status by calling the /v2/documents/{jobId} endpoint. These calls will consume your rate limit quota. We recommend a polling interval of at least 30 seconds.

---

Constraints and Error Handling:

• Supported Formats: For the list of supported document formats, see the /v2/documents/types endpoint. Using an unsupported format result in an error response.
• Language Pairs: For supported language pairs, see the /v2/languages/document-translation endpoint. Using an unsupported pair result in an error response.
• File Size: The maximum file size is 20 MiB. Uploading a larger file will result in an error response.
• Word Count: The document can contain at most 50,000 words. Exceeding this limit will cause the translation to fail.

Caution

The document is available for download for 1 hour, after that the document is deleted.

Request Body — REQUIRED
source BCP-47 — REQUIRED Possible values: 2 ≤ length ≤ 25 The source language of the translation.
target BCP-47 — REQUIRED Possible values: 2 ≤ length ≤ 25 The target language of the translation.
file binary — REQUIRED File to translate
successCallbackUrl uri Possible values: 1 ≤ length ≤ 256 The URL that will be called upon successful translation. The URL must be absolute and use the HTTPS protocol. If this field is not provided, no callback will be sent. In this case, the client must poll the API to determine when the translation is complete.
errorCallbackUrl uri Possible values: 1 ≤ length ≤ 256 The URL that will be called if the translation fails. The URL must be absolute and use the HTTPS protocol. If this field is not provided, no callback will be sent. In this case, the client must poll the API to determine when the translation is complete.
translationId Translation ID Possible values: length ≤ 64 Optional ID to identify the translation. It will be returned in the callbacks.

Responses
202 Successful response Schema — OPTIONAL jobId uuid Identifier of the started translation. This value can later be used to retrieve the translated file.
401 The access token provided is missing, expired, revoked, malformed, or invalid for other reasons. The client MAY request a new access token and retry the protected resource request. Schema — OPTIONAL detail Detail A generic JSON value, typically a string describing the error.
403 The request requires higher privileges than provided by the access token. The request should not be retried. Schema — OPTIONAL detail Detail A generic JSON value, typically a string describing the error.
422 Unsupported document format Schema — OPTIONAL detail Detail Unsupported document format
429 Too many requests in the time interval Schema — OPTIONAL detail Detail A generic JSON value, typically a string describing the error.
500 Internal server error Schema — OPTIONAL detail Detail A generic JSON value, typically a string describing the error.