Translating files using the Globalese API

Useful pages

Detailed documentation of API endpoints: https://globalese.atlassian.net/wiki/spaces/DOCS/pages/2232090723

Relevant end-user documentation explaining the workflow: https://globalese.atlassian.net/wiki/spaces/DOCS/pages/647233569

General requirements

All requests must be authenticated.
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.

Engine

A machine translation model capable of translating from one language to another.

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.

Project

A collection of files to be translated using the same settings, i.e. languages, group, and engine.

Translation projects involving multiple source or target languages will require multiple projects in Globalese.

What you will need to get started

Globalese instance base URL

Your Globalese instance URL, e.g. https://acme.globalese.ai. Requests must be sent to this base URL + /api/v3 + the endpoint.

Username and API key

Both can be found on a user’s profile page. All calls made to the API endpoints described below must be authenticated using a valid Globalese username and API key.

Suggested procedure

Summary

Create a project
Upload files
Create translation jobs
Poll project/file statuses
Download translated files
Clean up

1. Create a project

See GET /groups to list groups, and GET /engines to list engines.

Notes:

Being a member of a group does not necessarily mean having the required permissions to translate files. For the steps described here, the authenticated user must have MANAGE_PROJECTS permissions in the chosen group.
The project must be created in the same group that the chosen engine belongs to.
The status of the selected engine is important. Engines are only ready for translation if the actions.translate property in the GET /engines response is true.
Depending on the published property, some users may or may not be able to use an engine for translations. See https://globalese.atlassian.net/wiki/spaces/DOCS/pages/2259550220
A project can only have one engine assigned to it. The engine may be changed for an existing project, although this should not be necessary.

Requests:

GET /engines
GET /groups
POST /projects

2. Upload files

Files must be uploaded one at a time.

We recommend grouping files from the same project in a single corresponding Globalese project. The Globalese project should ideally exist throughout the lifetime of the source (or CAT tool) project, to allow any newly added or re-imported files to be processed in the same Globalese project.

We do not recommend creating one project per file sent to Globalese if the files are in the same project at the source, as this creates unnecessary overhead and extra API calls.

If a file is re-imported to the project, it is recommended to delete the old version of the file in the Globalese project and re-upload the file.

See the list of supported file formats here:

Requests:

POST /projects/{projectId}/files

3. Create translation jobs

We recommend triggering the translation of files in a project in one batch, i.e. creating translation jobs for each file one after the other, one at a time, immediately after receiving a response from the previous request.

Requests:

POST /jobs/translation

4. Poll project/file statuses

This behaviour is set to change in the future.

Right now, the status of translation jobs cannot be tracked, but new endpoints are planned that will enable this. In the future, instead of tracking file statuses, job statuses will need to be tracked.

Track the status of the project as a whole, or the status of the individual files. We don’t recommend sending more than one polling requests per minute.

Requests:

5. Download translated files

A file can be downloaded when its status changes to translated. If you are tracking on the project level, all project files are ready to be downloaded when the status of the project changes to translated.

Requests:

6. Clean up

After the translated files have been downloaded, we recommend deleting all files and projects from Globalese to prevent them from existing (i.e. taking up space unnecessarily) in Globalese forever.

Requests: