Segment-based translation using deployed engines

Owned by Greg Horváth (Unlicensed)
Last updated: Jun 07, 2024 by Gábor Bessenyei (Globalese)
4 min read

All APIs documented here are REST APIs using (i.e. accepting and returning) JSON.

General requirements

  1. All requests must be authenticated.

  2. The appropriate Content-Type and Content-Length headers must always be set when sending payloads in POST/PUT/PATCH requests.

Definitions

Globalese instance

The user’s Globalese system, accessible via a URL such as https://acme.globalese.ai or similar.

Translation service

The service accepting and processing segment-based translation requests. This service is independent of the Globalese instance.

Engine

A machine translation model capable of translating from one language to another. Translation projects involving multiple source or target languages will require multiple engines.

Group

Multiple groups can be created and used in Globalese. An engine always belongs to one specific group. Users may be members of more than one group, with different permissions in each.

Restrictions

  1. This functionality is only available in the cloud-based version of Globalese.

  2. Stock engines cannot be deployed.

Suggested procedure

The following is the outline of our preferred way of integrating the segment-based translation functionality with examples.

You are welcome to figure out your own approach based on the API documentation, but bear in mind that the API is opinionated towards the way we at Globalese imagine integration.

Summary

  1. Collect the basic information from the user necessary for making API calls.

  2. Make the user select an engine to use.

  3. Use the selected engine for translating one or multiple segments.

1. Collect the necessary information from the user

The data obtained here may be stored for a longer time, i.e. across sessions, but users must be able to change them in the future.

The user setting up the connection must provide:

  • The base URL of their Globalese instance (e.g. https://acme.globalese.ai)

  • A means of authentication. This can be:

    • A Globalese user’s API key (the user needs to have the required permissions).

    • An API key created specifically for using certain engines for segment-based translation. These API keys are not associated with any user in Globalese, and are generally intended to be used for allowing external users (such as translators/post-editors) to use the translation functionality without creating a user account for them in Globalese).

 

2. Query engine information using the Globalese instance API

See the API documentation here: Querying engine information and managing engine instances

Prerequisites:

  • Base URL, obtained from the user

  • Authentication, obtained from the user

 

2.1. When the user clicks the Connect button, get a list of engines, engine instances, languages and groups from Globalese.

If you already know what language combination is needed, add filters to the GET /engines call.

Engines

Engines with a non-empty instance_ids array have at least one instance (being) deployed.

The value of uuid must be used when making a call to the translation service.

Engine instances

The value of engine_id is the ID of the engine the instance has been created from.

If status is on, the engine instance is ready to accept translation requests.

The value of dispatcher_url is the service base URL needed to make a call to the translation service.

Requests:

GET <Globalese instance URL>/api/v3/engines?sort=name:asc GET <Globalese instance URL>/api/v3/engine-instances GET <Globalese instance URL>/api/v3/languages?usage=engines:source GET <Globalese instance URL>/api/v3/languages?usage=engines:target GET <Globalese instance URL>/api/v3/groups?sort=name:asc

2.2. Present an alphabetically sorted list of engines to the user. Engines that don’t have instances whose status is on should still be in the list for better context, but should be inactive (i.e. not selectable).

2.3. The larger an organisation is, the more likely they will have more engines. Therefore it is recommended to provide the following optional filtering options:

  • Source languages used in engines

  • Target languages used in engines

  • Groups

Differences by types of authentication

If the API key used for authenticating belongs to a Globalese user account, groups can be queried. If it is an API key for translation only, the GET /groups endpoint will return a 403 response. In this case, the Groups dropdown should be inactive or need not be displayed.

2.4 If any of these is selected, run a new query for engines using the source_language, target_language or group_ids query parameters.

Request:

GET <Globalese instance URL>/api/v3/engines?sort=name:asc&group_ids=1,2&source_language=en&target_language=de

3. Translate segments using the translation service API

See the API documentation here: Translating segments

Prerequisites:

  • Translation service base URL, obtained from the GET /engine-instances endpoint

  • Engine UUID, obtained from the GET /engines endpoint

 

Use the settings made previously to send one or multiple translatable segments to the translation service.

Request:

POST <translation service URL>/api/v1/translations