Translating segments

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

1 2 3 4 5 6 7 8 { "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:

1 2 3 4 5 6 { "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:

1 2 3 4 5 6 7 8 9 10 11 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>." ] }'