The Enterprise API makes it easy for integrators to export/re-import vendor-assigned tasks from/to the Enterprise TMS, so that they can be translated within a third-party CAT tool.

API Diagram

There is one recommended flow to support offline translation using Enterprise's API:

Receiving Callbacks when Tasks Are Available to Work On

Image Added

Example API Responses

GET /task

{
  "class": [
    "tasks",
    "Collection"
  ],
  "properties": {
    "limit": 10,
    "total": 1,
    "offset": 0,
    "size": 1
  },
  "entities": [
    {
      "class": [
        "task"
      ],
      "rel": [
        "task"
      ],
      "properties": {
        "project_name": "example.com",
        "translation_locale": "fr-FR",
        "title": "Example Document",
        "document_name": "example_document.txt",
        "author_email": "",
        "author_name": "",
        "business_division": "",
        "business_unit": "",
        "campaign_id": "",
        "campaign_rating": 0,
        "contact_email": "",
        "contact_name": "",
        "content_description": "",
        "domain": "http://example.com",
        "external_application_id": "a79ee237-4c69-4126-946d-cf9cfcf13ef1",
        "external_document_id": "40",
        "external_style_id": "",
        "purchase_order": "",
        "reference_url": "http://example.com/document",
        "weighted_words": null,
        "words": 1209,
        "document_id": "20f93bc9-ed5d-45af-c225-1e4384d73408",
        "translation_id": "682ee649-9449-2925-8f2a-c2ff76b0fe43",
        "project_id": "ccc57f52-2f92-418f-b884-8348e95c1be9",
        "content_type": "node",
        "progress": 0,
        "status": "WAITING",
        "id": "4186f3d5-c335-4e04-a123-94d40cdd20af",
        "channel": "",
        "region": ""
      },
      "links": [
        {
          "rel": [
            "self"
          ],
          "href": "/task/4186f3d5-c335-4e04-a123-94d40cdd20af"
        }
      ]
    }
  ],
  "links": [
    {
      "rel": [
        "self"
      ],
      "href": "/task?offset=0&limit=10"
    }
  ]
}

GET /task/{id}/content

"<?xml version='1.0' encoding='UTF-8'?> <xliff xmlns="urn:oasis:names:tc:xliff:document:1.2" version="1.2" xmlns:lgtk="http://www.lingotek.com/xliff/1.2"> ... </xliff>"

PATCH /task/{id}/content

{
  "processes": [
    "78f0e4d3-ee66-4b81-2aed-a621e46afe2a"
  ]
}

GET /process/{id}

{
  "class": [
    "process"
  ],
  "properties": {
    "title": "example_document_task.xlf",
    "duration": 27,
    "progress": 100,
    "status": "COMPLETED",
    "id": "78f0e4d3-ee66-4b81-2aed-a621e46afe2a"
  },
  "links": [
    {
      "rel": [
        "self"
      ],
      "href": "/process/78f0e4d3-ee66-4b81-2aed-a621e46afe2a"
    }
  ]
}

GET /document/{id}/translation/{locale}

{
  "class": [
    "translation"
  ],
  "properties": {
    "locale_code": "fr-FR",
    "start_date": 1510699127794,
    "complete_date": 0,
    "percent_complete": 50,
    "due_date": 0,
    "status": "IN_PROGRESS",
    "id": "682ee649-9449-2925-8f2a-c2ff76b0fe43"
  },
  "entities": [
    {
      "class": [
        "phases",
        "Collection"
      ],
      "rel": [
        "phases"
      ],
      "properties": {
        "limit": 2,
        "total": 2,
        "offset": 0,
        "size": 2
      },
      "entities": [
        {
          "class": [
            "phase"
          ],
          "rel": [
            "phase"
          ],
          "properties": {
            "auto_skip": true,
            "percent_completed": 0,
            "start_date": 0,
            "complete_date": 0,
            "is_completed": false,
            "due_date": 0,
            "status": "WAITING",
            "order": 2,
            "name": "Test",
            "id": "4186f3d5-c335-4e04-a123-94d40cdd20af",
            "type": "TRANSLATION"
          },
          "entities": [
            {
              "class": [
                "team_assignees",
                "Collection"
              ],
              "rel": [
                "team_assignees"
              ],
              "properties": {
                "limit": 0,
                "total": 0,
                "offset": 0,
                "size": 0
              }
            },
            {
              "class": [
                "assignees",
                "Collection"
              ],
              "rel": [
                "assignees"
              ],
              "properties": {
                "limit": 1,
                "total": 1,
                "offset": 0,
                "size": 1
              },
              "entities": [
                {
                  "class": [
                    "assignee"
                  ],
                  "rel": [
                    "assignee"
                  ],
                  "properties": {
                    "name": "Jack Robbins",
                    "id": "3423c9ec2-2ce3-264a-e181-9e9335c2dfff"
                  }
                }
              ]
            }
          ]
        },
        {
          "class": [
            "phase"
          ],
          "rel": [
            "phase"
          ],
          "properties": {
            "auto_skip": true,
            "percent_completed": 100,
            "start_date": 1510699127794,
            "complete_date": 1510699130643,
            "is_completed": true,
            "due_date": 0,
            "status": "READY",
            "order": 1,
            "name": "Translate",
            "id": "74f26f12-99c7-4e44-8873-1d380aa8735e",
            "type": "TRANSLATE"
          },
          "entities": [
            {
              "class": [
                "team_assignees",
                "Collection"
              ],
              "rel": [
                "team_assignees"
              ],
              "properties": {
                "limit": 0,
                "total": 0,
                "offset": 0,
                "size": 0
              }
            },
            {
              "class": [
                "assignees",
                "Collection"
              ],
              "rel": [
                "assignees"
              ],
              "properties": {
                "limit": 0,
                "total": 0,
                "offset": 0,
                "size": 0
              }
            }
          ]
        }
      ]
    },
    {
      "class": [
        "locale",
        "fr"
      ],
      "rel": [
        "locale"
      ],
      "properties": {
        "title": "French, France",
        "language_code": "fr",
        "country_code": "FR",
        "code": "fr-FR",
        "language": "French",
        "country": "France"
      },
      "links": [
        {
          "rel": [
            "self"
          ],
          "href": "/locale/fr-FR"
        }
      ]
    }
  ]
}

Example HTTP Notification

Request Origin: Enterprise

Request Destination: Integrator

Query Params

GET {callback_url}?doc_author_name=j.doe&locale_code=fr-FR&doc_content_description=&target_id=db65816a-e854-4b3e-b4f4-9eea10bae34c&doc_campaign_id=&document_id=20f93bc9-ed5d-45af-c225-1e4384d73408&phase_name=test&doc_purchase_order=&doc_mts=1537211244114&doc_business_unit=&doc_external_style_id=&projectId=60314&original_project_id=0&doc_cts=1537210928500&doc_channel=&doc_business_division=&locale=fr_FR&targetId=14638015&doc_domain_type=http%3A%2F%2Fexample.com%2Fdocument&doc_campaign_rating=0.0&doc_region=&complete=true&community_id=1c5f137b-d9d1-44c3-8ff0-24d0460943bb&progress=100&doc_content_type=pdf&project_id=ccc57f52-2f92-418f-b884-8348e95c1be9&status=COMPLETE&doc_reference_url=http%3A%2F%2F919bbbff.ngrok.io%2Fd84x%2Fd842b%2Fnode%2F1&documentId=5332301&type=target&doc_status=COMPLETE&doc_external_document_id=1&doc_contact_email=&doc_contact_name=&doc_external_application_id=a79ee237-4c69-4126-946d-cf9cfcf13ef1

Downloading Tasks

Use the following API calls to view and export your tasks. 

• GET /task allows you to view the list of tasks assigned to you in the TMS.

• Use Get

  GET /task/{id}/content

  to download

   downloads the XLIFF for a given task

Uploading A Completed Task

• Uploading completed XLIFF files to the TMS has the same effect as if you had worked within Lingotek's Workbench to perform the translations/edits. 
• We only re-import the translations and not any metadata from the XLIFF that may have been added to the file. 
• Authorship is attributed to the user re-importing the tasks through the API. 

Existing translations in the phase are overwritten by the ones in the XLIFF file.

Tip
A revision history for each segment is available on our Workbench.

• If there is no translation in the imported XLIFF the import process will skip over that segment. Leave it untranslated.
If there isn't text for a XLIFF file, then translations are not overwritten. 

.

Keep in mind the following as you are exporting tasks:

• Via the UI, a user is not able to download tasks (XLIFF files) that aren't in their Task List. Likewise, the API calls will need to authenticate using the credentials of the user to whom the task is assigned in Enterprise.

• You can only download XLIFF for 'Active' tasks (i.e. tasks that are ready to be worked on, but have not been skipped, canceled or 'marked complete' within Enterprise).

Editing XLIFF files

While you are editing the XLIFF files you should be aware of the following, so that you can re-import the files back into the TMS when you are finished editing:

• We follow the XLIFF 1.2 specification

• Be sure not to modify the number of trans-units, their order or identifiers

• Adding style to the corrections is not advisable. For example, if a translation were to change from "dog" to "puppy", "puppy" should simply replace "dog" and not be something like "dogpuppy."

• Do not merge or split segments within your tool. If our system detects that one or more segments were merged or split, the re-import will fail.

Attributes and metadata

• On export, we add a lgtk:phaseUUID attribute in the header of the XLIFF. This is what we match on when you re-import the XLIFF. Be sure that you do not remove this attribute. 

  If this

• The XLIFF files you download from Enterprise's TMS will only ever correspond to one target language. As such it is important that if you have an xml:lang for a segment it should match the target language in the header.

• Enterprise doesn't import any meta from the uploaded XLIFF. All we do is extract and import the translations form the trans-units. We do not import anything else from the XLIFF.

• All target attributes are optional, however, below is more information about target attributes if you include them. 

  • state: Different behavior can happen on XLIFF re-import depending on the state attribute.

  • xml:lang: If present, this should contain the locale code for the target locale, which is defined in the <file> tag's "target-language" attribute.

  • state-qualifier: This helps to clarify the origin of the translation. Click here for instructions on how to make these values appear in SDL Trados Studio. 

  • phase-name: This provides clarification as to which phase this target is in. The export provides a number, which has a description in the <phase group> section in the <header>. 

• mrk: <mrk> is optional, but if present, there must only be one per target, and it must surround the entire segment. If there is more than one <mrk> segment in a <target>, the import fails. If there is one that does not completely encapsulate the segment, only the text within the <mrk> is imported. 

• mid: Optional. Used as an identifier for a specific <mrk> within the target.

• mtype: REQUIRED. This is required by the XLIFF 1.2 specification. It describes the type of <mrk>. The export uses "seg" as the mtype. If mtype is not present, the import will fail.

Uploading A Completed Task

Upon completing a Task outside of Enterprise’s TMS, it is a simple process to push them back into the TMS. The following API calls will re-import content into the TMS. View the documentation here to troubleshoot any errors you may receive when uploading tasks to the TMS. 

• PATCH /task/content

• PATCH /task/{id}/content

Keep the following in mind as you re-import XLIFF file

(s) to complete your assigned task(s):

Process Completions

• PATCH /task/content and PATCH /task/{id}/content both schedule new jobs in the TMS for executing the the re-import process.

• The IDs for the re-import process(es) are included in the API response.

• GET /process/{id} can be used to get the status of a given process (e.g. to check if it failed or not; or if it successfully finished).

File Structure

• Be sure that the structure of the XLIFF has not changed. 

• We accept both zip folders containing XLIFF files or single XLIFF files.

• We only re-import the translations and not any metadata from the XLIFF that may have been added to the file.

Authentication

• Via the UI, a user is not able

  to download or re

  to re-import XLIFF for a task that isn't in their Task List

  (i.e. the task has to be assigned to you). Therefore

  . Likewise, the API calls will

  likewise

  need to authenticate using the credentials of the user to whom the task is assigned in

  Lingotek.

  Enterprise.

• Authorship is attributed to the user re-importing the tasks through the API. 

• You can only

  download /

  re-import XLIFF for 'Active' tasks (i.e. tasks that are ready to be worked on, but have not been skipped, canceled or 'marked complete' within

  Lingotek

  Enterprise).

• We're assuming that you won't be merging or splitting segments within your tool. If on re-import we detect that one or more segments were merged or split, the re-import will fail.
• We accept both zip folders containing XLIFF files or single XLIFF files.
• To send the XLIFF back use PATCH /task/{id}/content. Be sure that the structure of the XLIFF has not changed. 
If the document is completely correct and does not need any changes, you should still upload it back to the TMS and the system will note that the document

Effect on the TMS

• Existing translations in the phase are overwritten by the ones in the imported XLIFF file.

• When reviewing translations in a third-party CAT tool, you should always re-import the XLIFF file to the TMS even if you didn't need to make any edits to the translations. Re-importing an unedited XLIFF lets the TMS know that the assigned task was completed and did not need any edits

  . 

File Structure

• We follow XLIFF 1.2 spec. If the format is kept the same and the lgtk:phaseUUID is kept in the header, thereshouldn't be any compatability issues.
• Be sure to not modify the number of trans-units, their order or identifiers. 
• The XLIFF files will only ever correspond to one target language

FAQ

If no changes have been made to the document, should we upload an unchanged document? 

• If the document is completely correct and does not need any changes, you should still upload it back to the TMS and the system will note that the document was completed and did not need any edits. 

Which time zones we should use when update the modify date? It seemed that Lingotek will update the modify time after uploading.

• Lingotek doesn't import any meta from the uploaded XLIFF. All we do is extract the translations form the trans-units. We ignore everything else. Modified dates for each segment translation will be set in our system based on the upload time.

• ; and will be reflected as such in your Task List upon successfully re-importing the XLIFF file. 

• If there is no translation for a segment when the XLIFF file was downloaded, and there still is not a translation when it is re-imported back into the TMS, the import process will skip over that segment and it will appear as a non-translated segment.

• If a segment has a translation in the XLIFF upon download, but the <target> is blank upon re-import, the TMS will keep the previous translation.