Show / Hide Table of Contents

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
In This Page
Back to top