Translating segments

The APIs in this part of the documentation are in beta, and may be subject to change without prior notice.

Authentication

Authentication must be provided in the request header as Authorization: Bearer <API key>.

API keys for segment-based translation

A valid API key can be:

A user's API key. The user must have translate permission in the group the engine belongs to.
An API key for translation that has been assigned to the engine.

Parameters necessary for making a request

Apart from the sentences to be translated, the following information is always required for making successful requests – and should never be hardcoded in client implementations:

Parameter	Usage
Service base URL	Requests must be sent to this base URL + `/api/v1` + the endpoint. This URL is determined by the region in which the engine is deployed.
API key	Must be sent among the request headers as `Authorization: Bearer <API key>`
Engine ID	The UUID of the engine to be used for translating segments. Must be sent in the JSON payload as `engine_id`

Endpoints

The latest API version is v1.

POST /translations

JSON payload

Parameter	Required	Type	Usage
`engine_id`	yes	`string`	The UUID of the engine to use.
`sentences`	yes	`string[]`	The sentences to be translated. They can be: Plain text XML fragment Well-formed XLIFF 1.2 or XLIFF 2.1 (there is no need to wrap/envelope the sentences in anything, i.e. you can send whatever is inside the `<source>` tag)
`format`	no	`string`	The format of all the sentences sent in the same request in the `sentences` array. Accepted values: `text-plain` `xliff:1.2` `xliff:2.1` GLOBALESE 4.1.2+ `xml` GLOBALESE 4.1.2+ If this parameter is not provided, Globalese will use its best guess. It is recommended to always specify the format if known and never leave it to Globalese to auto-detect, whenever the format is known. In case translatable segments have different formats, they must be sent in separate requests.

Limits

The maximum request size is 100 kilobytes.

Example request

{
    "engine_id": "<engine ID>",
    "format": "xliff:1.2",
    "sentences" : [
        "Sentence one.",
        "Sentence <g id=\"1\">two</g>."
    ]
}

Example response

A successful response has a 201 response code and the following body structure:

{
    "sentences": [
        "Translation one.",
        "Translation <g id=\"1\">two</g>."
    ]
}

Other response codes:

400 Bad Request
401 Unauthorized
413 Payload Too Large
500 Internal Server Error
502 Bad Gateway (error during translation)

cURL example

The following request shows a full cURL request to /translations:

curl --location --request POST '<service URL>/api/v1/translations' \
--header 'Authorization: Bearer <API key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "engine_id": "<engine ID>",
    "format": "xliff:1.2",
    "sentences" : [
        "Sentence one.",
        "Sentence <g id=\"1\">two</g>."
    ]
}'