Continuous Localization Integration

Use Lingotek’s fully RESTful APIs to build your own continuous localization integration (first, see our supported connectors for out-of-the-box support). By continuous localization, we mean that as soon as you send content for localization it will immediately be quoted, assigned, translated, and returned back to its original source without any manual effort on your part. This model also supports automatically updating edited source content at any point in the translation process without interruptions. The Lingotek platform will seamlessly accept this new version of the document without complications.

API Diagram

Open

Additional Details

Getting Set Up

1. Before making any API calls to upload documents to the TMS, the integration will need to use an access token associated with a user in the Lingotek TMS who:

   1. Has at least the Project Manager role in the TMS. 

   2. Is at least a Shared User of the project where you will be uploading the documents.

2. Have your connector gather your token by providing this link. The user with the token will sign in and you can automatically gather the API token after they log in during the redirect.

3. GET /project – Choose a project to link to. Use the endpoint to display a list of projects your end-user to choose from.

   1. Alternatively, you can also get the UUID of the preferred project from the TMS UI and manually store it in your integration. This isn’t recommended if you want end-users to change the project they are linked to whenever necessary.

   2. For the continuous translation model, it is simplest to link to a single project. However, if you want different flows for different types of content, link to a different project for different content types.

4. POST /project/{id}/callback – Set the callback URL on the project using this endpoint.

   1. After you choose the project(s) you are sending content to, tell the project where it should send important status updates about your content.

   2. This will automate communication around document import, target completion, archive, deletion, etc. without polling the Lingotek TMS.

5. GET /workflow – Get a list of workflows.

   1. The workflow is the steps your content will take during localization.

   2. We recommend you simply rely on the project’s workflow since it is easier for your TMS admins to maintain.

      1. Leave the translation_workflow_id parameter blank when you request translations to use the project workflow.

      2. If you use the project workflow, then you don’t need to use the GET /workflow call.

   3. For a more complex integration, you can set up an interface to specify workflows for different locales or content types. Or allow the user to choose the workflow with each upload. This is not necessary for most organizations.

6. We highly recommend controlling which locales your end users can request.

   1. The translations your organization requests requires careful consideration.

   2. Allowing any user to request any of the locales Lingotek supports could lead to budget and operational issues for your localization team.

   3. Here is a list of supported locales in the Lingotek TMS.

   4. GET /locale - Use this endpoint to get a list of supported locales and store it in your integration. Lingotek occasionally adds new locales to this list.

   5. Have someone choose which locales can be requested from your integration and limit your content managers to this list.

Uploading a new document

POST /document – Upload the file to the Lingotek TMS.

1. You can only upload supported file types via the API.

2. Required fields:

   1. title – This will be the name of the document in the TMS.

   2. content – The file (either raw text or a path to the file) that you want to translate.

   3. format – The file type in Okapi that this should be treated as. See our supported file type document to map file types to the correct format field.

3. Set all the locales you want to be translated in the initial POST /document call using the translation_locale_code parameter. Each translation can have its own unique workflow and other settings.

4. See our Document endpoint documentation for specific details about this endpoint, but other valuable parameters to specify include:

   1. external_url – This is the URL where your source content is hosted (if it is web-based content). We load this URL in our Workbench so end-users can translate in context.

   2. note – Allow the content manager to provide specific context about the source document they are uploading.

   3. due_date – The date the content manager requests for all requested translations to be returned.

   4. Secondary metadata fields – We support 20+ metadata fields that will enhance reporting and trigger automation.

5. This is an asynchronous API call and you can only take action on the document after it imports successfully.

   1. The UUID the system will assign to the document when it successfully imports.

   2. Wait for the document_uploaded callback to let you know the document imported successfully.

   3. If, for whatever reason, your document fails to import the import_failure call will be sent.

Actions during the translation process

There are four main actions to take while the document and its translations are in progress.

1. POST /document/{id}/translation – Request a new translation on the uploaded document.

   1. You need to wait until the document is successfully imported to add more translations to the document.

2. PATCH /document/{id} – Use this call to upload a new version of the document.

   1. You can make this call at any point in the translation process.

   2. The successful 202 response will include a new document UUID. You need to replace the old UUID you are storing with this one.

   3. The Lingotek TMS tracks all the versions of the document for a complete history. If you make a call on an old document version, we will continue to provide you with the latest document UUID so you can update your mapping.

3. PATCH /document/{id}/cancel – Use this call to cancel the document and its translations while it is still in progress.

   1. Cancelled documents cannot be reactivated.

   2. You should allow users to re-upload the cancelled document using the POST /document call after the asset is cancelled.

4. PATCH /document/{id}/translation/{locale}/cancel – Use this endpoint if you want to cancel a single target in the document.

   1. Cancelled targets cannot be reactivated.

   2. If you need that translation to resume, you will need to use the PATCH /document/{id} call for that translation to continue.

Callbacks to watch after POST /document

There are several callbacks to watch for while the document and its translations are in progress.

1. TARGET – This callback is primarily used to let you know when you can download a completed translation.

   1. You will receive this callback at various times, but you should only download a translation when the ready_to_download parameter equals true.

2. TARGET_DELETED – Deletion is NOT a recommended action from the API.

   1. Occasionally, users will delete targets while in the TMS.

   2. This allows you to record the translation no longer exists in the TMS and will need to be requested again if necessary.

3. TARGET_CANCELLED – If a user from your connector cancels a target, or someone cancels it from the TMS, this callback will let you know so you can update your status.

4. DOCUMENT_DELETED – Deletion is NOT a recommended action from the API.

   1. If the document is deleted, this callback will let you know so you can update the status in your connector.

   2. You will need to upload the asset using the POST /document endpoint.

5. DOCUMENT_ARCHIVED – When the document is archived, this callback will let you know so you can update the status in your connector.

6. DOCUMENT_UPDATED – After you update a document, wait for this callback so you know it has successfully updated.

7. DOWNLOAD_INTERIM_TRANSLATION – You receive this callback when the workflow administrator has specifically requested you download translations at this point in the workflow, even if the target has not been completely translated. This is usually done to quickly populate content with MT, or to allow easier access to in-country reviewers. When the workflow has finished completely, you will download the translation again and overwrite the interim translation.

Downloading completed translations

GET /document/{id}/content – Call this endpoint when the TARGET callback is received and the ready_to_download parameter is set to TRUE to download the translation.

Launch the Lingotek Workbench for updates

If content managers need to make any changes to translations they can launch the Lingotek Workbench directly from your integration.

1. Use this deeplinking formula to launch the Workbench https://myaccount.lingotek.com/workbench/document/{uuid}/locale/{locale-code}

2. You should only allow users to launch the Workbench when the target has been completed.

3. As users make edits, you can expect another target callback letting you know updates have been made.

4. Users need to have a Lingotek account to access the Workbench.

On this page