Show / Hide Table of Contents

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

* input - The file limit is set to 100 MB and the total size of the processable input content must not exceed 2 million characters.

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