Translating files using the globalese by memoQ API

Useful pages

Detailed documentation of API endpoints: globalese by memoQ API v3

Relevant end-user documentation explaining the workflow: Document translation

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 by memoQ instance

The user’s globalese by memoQ 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 by memoQ. 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 by memoQ.

What you will need to get started

globalese by memoQ instance base URL

Your globalese by memoQ 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 by memoQ username and API key.

Suggested procedure

Summary

  1. Create a project

  2. Upload files

  3. Create translation jobs

  4. Poll project/file statuses

  5. Download translated files

  6. Clean up

1. Create a project

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

Notes:

  1. 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.

  2. The project must be created in the same group that the chosen engine belongs to.

  3. 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 Publishing engines

  4. 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 by memoQ project. The globalese by memoQ 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 by memoQ project.

We do not recommend creating one project per file sent to globalese by memoQ 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 by memoQ project and re-upload the file.

See the list of supported file formats here: Integration

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:

GET /projects/{projectId}/files/{fileId}
GET /projects/{projectId}/files
GET /projects/{projectId}

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:

GET /projects/{projectId}/files/{fileId}/translated-file
GET /projects/{projectId}/translated-files

6. Clean up

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

Requests:

DELETE /projects/{projectId}/files/{fileId}
DELETE /projects/{projectId}