Create the translation
This call creates the translation by sending the input and the parameters Multipart form data.
Linux
curl -XPOST \
-H "Content-Type:multipart/form-data" \
-H "Authorization:Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" \
-H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" \
-F "sourceLanguageId=eng" \
-F "targetLanguageId=fra" \
-F "model=generic" \
-F "input=@\"./demo.txt\";filename=\"demo.txt\"" \
-F "inputFormat=PLAIN" \
-F "qualityEstimation=1" \
-F "translationMode=quality" \
-F "dictionaries=703e2693-704f-4588-8e9c-97799eeb75ae" \
-F "dictionaries=ab783076-c9e0-4557-8f06-8be9055fa34c" \
-F "labels=c3afbd44-4969-4677-83a7-4c7073e49ac1" \
-F "labels=74206abc-4b7a-466a-a6bd-080a2dd880df" \
-F "pdfConverter=SMART_SELECTION" \
-F "linguisticOptions={"formality":"Polite"}" \
'https://api.languageweaver.com/v4/mt/translations/async'
Windows
curl -XPOST^
-H "Content-Type:multipart/form-data"^
-H "Authorization:Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI"^
-H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555"^
-F "sourceLanguageId=eng"^
-F "targetLanguageId=fra"^
-F "model=generic"^
-F "input=@\"demo.txt\";filename=\"demo.txt\""^
-F "inputFormat=PLAIN"^
-F "qualityEstimation=1"^
-F "translationMode=quality"^
-F "dictionaries=703e2693-704f-4588-8e9c-97799eeb75ae"^
-F "dictionaries=ab783076-c9e0-4557-8f06-8be9055fa34c"^
-F "labels=c3afbd44-4969-4677-83a7-4c7073e49ac1"^
-F "labels=74206abc-4b7a-466a-a6bd-080a2dd880df"^
-F "pdfConverter=SMART_SELECTION"^
-F "linguisticOptions={\"formality\":\"Polite\"}" ^
https://api.languageweaver.com/v4/mt/translations/async
Access token type
User credentials - Allowed User Roles: Admin, Linguist, Translator
API credentials
HTTP Request
POST /v4/mt/translations/async
Headers
| Name | Value (example) | Description |
|---|---|---|
| Authorization | Bearer asd0eXAi... | Bearer token |
| Trace-ID | 2c0c4dda-8333-4538-983e-e098de7cf555 | Optional unique request identifier (UUID) provided by client |
Request Body:
(Request Body)
--8MsmExZ-SgFlDSniddeMZOkUV90emq
Content-Disposition: form-data; name="input"
Content-Type: application/octet-stream
Content-Length: 9
doc 1
--8MsmExZ-SgFlDSniddeMZOkUV90emq
Content-Disposition: form-data; name="sourceLanguageId"
Content-Type: text/plain;charset=UTF-8
Content-Length: 3
eng
--8MsmExZ-SgFlDSniddeMZOkUV90emq
Content-Disposition: form-data; name="targetLanguageId"
Content-Type: text/plain;charset=UTF-8
Content-Length: 3
fra
--8MsmExZ-SgFlDSniddeMZOkUV90emq
Content-Disposition: form-data; name="model"
Content-Type: text/plain;charset=UTF-8
Content-Length: 7
generic
--8MsmExZ-SgFlDSniddeMZOkUV90emq
Content-Disposition: form-data; name="inputFormat"
Content-Type: text/plain;charset=UTF-8
Content-Length: 10
PLAIN
--8MsmExZ-SgFlDSniddeMZOkUV90emq
Content-Disposition: form-data; name="submission-type"
text
--8MsmExZ-SgFlDSniddeMZOkUV90emq--
Content-Disposition: form-data; name="dictionaries"
a5805422-7ed3-4702-bbf9-339e180dd280
--8MsmExZ-SgFlDSniddeMZOkUV90emq--
Content-Disposition: form-data; name="dictionaries"
c215e1e6-8ccd-4f31-9acd-3c025976e907
--8MsmExZ-SgFlDSniddeMZOkUV90emq--
Content-Disposition: form-data; name="labels"
c3afbd44-4969-4677-83a7-4c7073e49ac1
--8MsmExZ-SgFlDSniddeMZOkUV90emq--
Content-Disposition: form-data; name="labels"
74206abc-4b7a-466a-a6bd-080a2dd880df
--8MsmExZ-SgFlDSniddeMZOkUV90emq--
Content-Disposition: form-data; name="pdfConverter"
SMART_SELECTION
--8MsmExZ-SgFlDSniddeMZOkUV90emq--
Content-Disposition: form-data; name="linguisticOptions"
{"formality": "Polite"}
--8MsmExZ-SgFlDSniddeMZOkUV90emq--
Request Parameters
Format
multipart/form-data
| Name | Type | Mandatory | Default value | Description |
|---|---|---|---|---|
sourceLanguageId |
string | yes | Three letters language code of the source language or auto which signals that the source language should be auto detected | |
targetLanguageId |
string | yes | Three letters language code of the target language | |
model |
string | no* | See notes below | A string representing a unique identifier for the language pair combination sourceLanguageId-targetLanguageId-model. (e.g. generic) |
submissionType |
string | no | text | This can be: text |
inputFormat |
string | no | PLAIN | Format of input content. See Input Formats. |
input |
file | yes | The binary content of the file | |
dictionaries |
string | no | empty | A multi value parameter containing dictionary ids |
labels |
string | no | empty | A multi value parameter containing label ids |
translationMode |
string | no | quality | A string representing a translation mode. Currently we support two translation modes: "speed" and "quality". In “quality mode”, our algorithms perform an extended statistical search, which sometimes results in a better quality output. “Speed mode” is instead optimized towards returning a translation as fast as possible. |
pdfConverter |
string | no | STANDARD | A string representing a pdf converter. Currently there are three supported options for the pdf converter: "SMART_SELECTION", "ABBYY" and "STANDARD". "ABBYY" is used with better results for scanned PDFs. With "SMART_SELECTION" Language Weaver will choose the best pdf converter option for given input, the choice will be made between "ABBYY" and "STANDARD". |
includeTextContent |
boolean | no | false | Boolean value that can be used to obtain text version of the file translation. If this property is set to true, translation result will be available in the text file version along with the one with expected output format. |
linguisticOptions* |
object | no | Object containing pairs of linguistic option name and value. Values are case sensitive. You can only use the linguistic options that are available for that specific language pair. You can see what linguistic options are available for a language pair using this API call: Linguistic Options | |
qualityEstimation* |
int | no | 0 | Numeric value specifying whether or not quality estimation should be computed. 0 - without quality estimation 1 - with quality estimation |
* linguisticOptions - in order to use linguistic options, the corresponding feature needs to be enabled on the account.
* qualityEstimation - in order to use quality estimation, the corresponding feature needs to be enabled on the account. The feature is available only for the language pairs that have the genericqe model.
Note
sourceLanguageId, targetLanguageId, model - can be used in the following combinations:
- sourceLanguageId=[languageName] and targetLanguageId=[languageName] and model=[identifier for the language pair] - when all three are used they uniquely identify a language pair e.g: Eng-Fra-generic
- sourceLanguageId=auto, targetLanguageId=[languageName], model- will be ignored even if specified - A language pair that matches the detected source language and the specified target language will be automatically selected. The selected language pair will be the first one (in alphabetical order) available in your account that matches the selection. E.g. if the detected source language is eng and the target language is fra and your account has subscriptions to (EngFra-Generic, EngFra-Sports, EngFra-Sports123) the language pair selected will be EngFra-Generic.
- source language needs to be provided for translations with image input formats
Note
- For image input formats, output format is PLAIN text (.txt)
- For EML and MSG input formats, output format is PLAIN text (.txt)
- For PDF input format, output format is DOCX (.docx)
- For all other input formats, output format is the same as the input format
Response JSON:
{
"sourceLanguageId": "eng",
"targetLanguageId": "fra",
"model": "generic",
"type": "resource",
"inputFormat": "PDF",
"requestId":"gfui83oah"
}
Response
Headers
| Name | Value (example) | Description |
|---|---|---|
| BeGlobal-Request-ID | dbbbc062-88a7-4783-8d52-dea795e517f4 | Unique request identifier (UUID) |
| Trace-ID | 2c0c4dda-8333-4538-983e-e098de7cf555 | The identifier provided in the request (UUID) |
Format
JSON
| Name | Type | Description |
|---|---|---|
sourceLanguageId |
string | Three letters language code of the given or the detected source language |
targetLanguageId |
string | Three letters language code of the target language |
model |
string | A string representing a unique identifier for the language pair combination sourceLanguageId-targetLanguageId-model. (e.g. generic) |
inputFormat |
string | Format of input content |
submissionType |
string | This can be: text |
requestId |
string | The id of the translation request. This has to be used for the subsequent calls |
{
"errors":[
{
"code":47,
"description":"sourceLanguageId language is not code 3 format or auto. (was 5)"
}
]
}
Error Response
Format
JSON
| Name | Type | Description |
|---|---|---|
errors |
list | A list with the errors that occurred |
code |
integer | The code of the error |
description |
string | The description of the error |
Returned HTTP Codes:
| Http Code | Description |
|---|---|
| 202 | When the translation is successfully initiated |
| 400 | When the input data is not valid |
| 401 | When the authentication process failed or the access token is not valid |
| 403 | Forbidden to access resource |
| 500 | Application internal error |
Note
The file limit is set to 100 MB.
Check the translation status
This call will allow the user to check the status of a previously created translation.The translation status can be: INIT, DONE, TRANSLATING, FAILED. If the translation is DONE the content of the translation can be retrieved. If the translation is TRANSLATING then the status call has to be triggered again. If the translation is FAILED then it needs to be submitted again.
Linux
curl -XGET -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' \
'https://api.languageweaver.com/v4/mt/translations/async/gfui83oah'
Windows
curl -XGET -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" ^
https://api.languageweaver.com/v4/mt/translations/async/gfui83oah
Access token type
User credentials - Allowed User Roles: Admin, Linguist, Translator
API credentials
HTTP Request
GET /v4/mt/translations/async/gfui83oah
Headers
| Name | Value (example) | Description |
|---|---|---|
| Authorization | Bearer asd0eXAi... | Bearer token |
| Trace-ID | 2c0c4dda-8333-4538-983e-e098de7cf555 | Optional unique request identifier (UUID) provided by client |
Query Parameters
| Name | Type | Mandatory | Default value | Description |
|---|---|---|---|---|
includeProgressInfo |
boolean | no | false | Boolean specifying if the translation progress must be included in the translation status response |
Response JSON:
{
"translationStatus":"TRANSLATING",
"translationProgress": 42,
"translationStats": {
"inputCharCount": 26
}
}
{
"translationStatus": "DONE",
"inputFormat": "PLAIN",
"outputFormat": "PLAIN",
"translationStats": {
"inputWordCount": 5,
"inputCharCount": 26,
"inputByteCount": 26,
"translationWordCount": 5,
"translationCharCount": 21,
"translationByteCount": 22
},
"translationProgress": 100,
"qualityEstimation": [
{
"poor": 0,
"adequate": 25,
"good": 75
}
]
}
Response
Headers
| Name | Value (example) | Description |
|---|---|---|
| BeGlobal-Request-ID | dbbbc062-88a7-4783-8d52-dea795e517f4 | Unique request identifier (UUID) |
| Trace-ID | 2c0c4dda-8333-4538-983e-e098de7cf555 | The identifier provided in the request (UUID) |
Format
JSON
| Name | Type | Description |
|---|---|---|
translationStatus |
string | A string representing the status of the translation. Can be one of the following INIT - input content was received by system and will be validated TRANSLATING - the translation process is in progress DONE - the translation was completed. When this status is returned then the Retrieve Content call should be triggered. FAILED - the translation failed. When this status is returned the Get Status calls should stop because there is no way to recover from this state. |
translationStats |
object | Statistics about the translation |
inputFormat |
string | Format of input content |
outputFormat |
string | Format of output content |
inputWordCount |
int | Number of input words in the source translated |
inputCharCount |
int | Number of input characters in the source translated |
inputByteCount |
int | Number of input bytes in the source translated |
translationWordCount |
int | Number of output words in the source translated |
translationCharCount |
int | Number of output characters in the source translated |
translationByteCount |
int | Number of output bytes in the source translated |
translationProgress |
int | Integer specifying the translation's progress. The value is populated based on includeProgressInfo query parameter value. |
qualityEstimation |
array | Array containing quality estimation percentages corresponding to the input content. The values are returned only when the translation has status DONE. The quality estimation labels are: good, adequate, poor. |
{
"errors": [{
"code": 43,
"description": "Unknown status for requestId {0}"
}]
}
Error Response
Format
JSON
| Name | Type | Description |
|---|---|---|
errors |
list | A list with the errors that occurred |
code |
integer | The code of the error |
description |
string | The description of the error |
Returned HTTP Codes:
| Http Code | Description |
|---|---|
| 200 | When the translation status is successfully returned |
| 400 | When the input data is not valid |
| 401 | When the authentication process failed or the access token is not valid |
| 403 | Forbidden to access resource |
| 500 | Application internal error |
Note
- When the translation status is "TRANSLATING", the response will include the inputCharCount from the translation statistics
- When the translation status is "DONE", in the response, we will return also the complete translation statistics
- When the translation status is "FAILED", in the response we will return also the failure reason
Retrieve the translated content
This call will allow the user to get the resulted translation.
Linux
curl -XGET -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' \
'https://api.languageweaver.com/v4/mt/translations/async/gfui83oah/content'
Windows
curl -XGET -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" ^
https://api.languageweaver.com/v4/mt/translations/async/gfui83oah/content
Access token type
User credentials - Allowed User Roles: Admin, Linguist, Translator
API credentials
HTTP Request
GET /v4/mt/translations/async/gfui83oah/content
Headers
| Name | Value (example) | Description |
|---|---|---|
| Authorization | Bearer asd0eXAi... | Bearer token |
| Trace-ID | 2c0c4dda-8333-4538-983e-e098de7cf555 | Optional unique request identifier (UUID) provided by client |
Query Parameters
| Name | Type | Mandatory | Default value | Description |
|---|---|---|---|---|
format |
string | no | String value used to retrieve translation result with a specified format. Valid values: "text". |
Note
If translations was initiated with includeTextContent set to true, the translation result can be retrieved in text format using query param format with value text
Response
Headers
| Name | Value (example) | Description |
|---|---|---|
| BeGlobal-Request-ID | dbbbc062-88a7-4783-8d52-dea795e517f4 | Unique request identifier (UUID) |
| Trace-ID | 2c0c4dda-8333-4538-983e-e098de7cf555 | The identifier provided in the request (UUID) |
Format
BINARY
The binary content of the translated file is returned.
{
"errors": [{
"code": 42,
"description": "Invalid requestId {0}"
}]
}
Error Response
Format
JSON
| Name | Type | Description |
|---|---|---|
errors |
list | A list with the errors that occurred |
code |
integer | The code of the error |
description |
string | The description of the error |
Returned HTTP Codes:
| Http Code | Description |
|---|---|
| 200 | When the translated content is successfully returned |
| 400 | When the input data is not valid |
| 401 | When the authentication process failed or the access token is not valid |
| 403 | Forbidden to access resource |
| 500 | Application internal error |
Retrieve the translated content for multiple translations
This call will allow the user to retrieve multiple translations based on a set of given request ids. All requested translations must have the status DONE, otherwise the request is rejected.
Linux
curl -XPOST -H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' -d \
'{"requestIds": ["gfui83oah", "afui12oac"]}' \
'https://api.languageweaver.com/v4/mt/translations/async/content/batch'
Windows
curl -XPOST -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" -d ^
"{\"requestIds\": [\"gfui83oah\", \"afui12oac\"]}" https://api.languageweaver.com/v4/mt/translations/async/content/batch
Access token type
User credentials - Allowed User Roles: Admin, Linguist, Translator
API credentials
HTTP Request
POST /v4/mt/translations/async/content/batch
Headers
| Name | Value (example) | Description |
|---|---|---|
| Authorization | Bearer asd0eXAi... | Bearer token |
| Trace-ID | 2c0c4dda-8333-4538-983e-e098de7cf555 | Optional unique request identifier (UUID) provided by client |
Request Parameters
Format
JSON
| Name | Type | Mandatory | Default value | Description |
|---|---|---|---|---|
requestIds |
list | yes | List of translation identifiers that need to be retrieved. List size is limited to 10. |
Response
Headers
| Name | Value (example) | Description |
|---|---|---|
| BeGlobal-Request-ID | dbbbc062-88a7-4783-8d52-dea795e517f4 | Unique request identifier (UUID) |
| Trace-ID | 2c0c4dda-8333-4538-983e-e098de7cf555 | The identifier provided in the request (UUID) |
| Content-disposition | attachment;filename=translations-4-20210920072212.zip | Contains the archive name (translations-{accountId}-{timestamp}.zip) |
Format
BINARY
A zip archive containing all the requested translated files will be returned.
{
"errors": [{
"code": 44,
"description": "Translation not found for requestId {0}"
}]
}
Error Response
Format
JSON
| Name | Type | Description |
|---|---|---|
errors |
list | A list with the errors that occurred |
code |
integer | The code of the error |
description |
string | The description of the error |
Returned HTTP Codes:
| Http Code | Description |
|---|---|
| 200 | When the translated content is successfully returned |
| 400 | When the input data is not valid |
| 401 | When the authentication process failed or the access token is not valid |
| 403 | Forbidden to access resource |
| 500 | Application internal error |