Create the translation
Translation Example:
Linux
curl -X POST -H "Content-type: application/json" \
-H 'Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI' -H 'Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555' -d '{"input":["Have a nice week!"],
"sourceLanguageId": "eng",
"targetLanguageId": "fra",
"model": "generic",
"inputFormat": "PLAIN",
"translationMode": "quality",
"dictionaries": ["0d967785-2857-46d7-9e10-4f6d1346db06", "717e47fa-0293-4898-b218-f948720f5321"],
"linguisticOptions": {"formality":"Polite"},
"qualityEstimation": 1 }' \
https://api.languageweaver.com/v4/mt/translations/async
Windows
curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer asd0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI" -H "Trace-ID: 2c0c4dda-8333-4538-983e-e098de7cf555" -d ^
"{^
\"sourceLanguageId\": \"eng\",^
\"targetLanguageId\": \"fra\",^
\"inputFormat\": \"PLAIN\",^
\"model\": \"generic\",^
\"input\": [\"Have a nice week\"],^
\"dictionaries\": [\"0d967785-2857-46d7-9e10-4f6d1346db06\", \"717e47fa-0293-4898-b218-f948720f5321\"],^
\"linguisticOptions\": {\"formality\":\"Polite\"}, ^
\"qualityEstimation\": 1 ^
}" https://api.languageweaver.com/v4/mt/translations/async
This call creates the translation by sending the input and the parameters as a JSON object.
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 Parameters
Format
JSON
| 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 |
input* |
array | yes | Content to be translated | |
dictionaries |
string array | no | empty | A string array containing dictionary 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. |
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 |
Text Input formats
| Name | Description |
|---|---|
HTML |
HTML |
PLAIN |
Plain text (UTF8) |
XLINE |
Plain text, one sentence per line |
TMX |
Translation Memory eXchange |
XLIFF |
XML Localization Interchange File Format |
BCM |
Proprietary format |
XML |
Extensible Markup Language |
SDLXML |
Treats every closing XML tag in the input as the end of a segment. The XML format in contrast does not make this assumption. |
Request JSON:
{
"sourceLanguageId": "eng",
"targetLanguageId": "fra",
"model": "generic",
"submissionType": "text",
"inputFormat": "PLAIN",
"translationMode": "quality",
"input":[
"Have a nice week!"
],
"dictionaries": ["0d967785-2857-46d7-9e10-4f6d1346db06", "717e47fa-0293-4898-b218-f948720f5321"],
"linguisticOptions" : {
"formality": "Polite"
},
"qualityEstimation": 1
}
* input - A JSON array where each element represents a separate text entry. Array entries are treated as distinct values and processed individually. The total size of the processable input content must not exceed 2 million characters.
Example: ["Have a nice week!", "Good morning!", "How are you?"]
* 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.
- dictionaries - if multiple dictionaries are used for a translation and they contain the same source, the match from the first dictionary in the list will be applied.
Response JSON:
{
"sourceLanguageId": "eng",
"targetLanguageId": "fra",
"model": "generic",
"submissionType": "text",
"inputFormat": "PLAIN",
"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 |
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 |
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, TRANSLATING, DONE, 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/{requestId}
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
}
{
"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 - source text 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. |
inputFormat |
string | Format of input content |
outputFormat |
string | Format of output content |
translationStats |
object | Statistics about the translation |
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 array input. These 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 "DONE", in the response, we will return also the 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 |
Response JSON:
{
"sourceLanguageId": "eng",
"targetLanguageId": "fra",
"model": "generic",
"translation":[
"Avoir une bonne semaine!"
]
}
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 |
translation |
string array | Array with the translated inputs |
{
"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 |