Downloading Tasks

Our API calls make it easy for LSPs to export the tasks assigned to them from our TMS and translate them in their own CAT tools. Your project and community settings in the TMS must allow for offline translation before you can use the APIs.

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.
GET /task/{id}/content downloads the XLIFF for a given task.

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 Lingotek.
You can only download XLIFF for 'Active' tasks (i.e. tasks that are ready to be worked on, but have not yet been 'marked complete' within Lingotek).

Editing XLIFF files

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

We follow XLIFF 1.2 specifications.
Be sure not to modify the number of trans-units, their order or identifier.
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 "~~dog~~puppy."
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.

Note
If the lgtk:phaseUUID attribute is missing, you will not be able to successfully re-import the XLIFF file.

The XLIFF files you download from Lingotek'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.

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.

Tip

title	Example

Modified dates for each segment translation will be set in our system based on the upload time. There is no need to add a modified date to a segment.

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.

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

Tip

title	Example

phase-name="1" might correspond to the following in the header: <phase phase-name="1" process-name="Translate"/>

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.

Tip

title	Example

Correct: <target...><mrk mtype="seg">This is my translation</mrk></target>

Incorrect: <target...>This <mrk mtype="seg">text</mrk> is translated</target> (Will only import "text")

Incorrect: <target...><mrk mtype="seg">This is one</mrk><mrk mtype="seg">too many mrk tags.</mrk></target>

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 Lingotek's TMS, it is a simple process to push them back into the TMS. The following API calls will upload content into the TMS.

PATCH /task/{id}/content.

Keep the following in mind as you reimport your completed task:#children-section { display:none !important; } #comments-section { display:none !important; } #likes-and-labels-container { display:none !important; } .page-metadata {display:none;}

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.

Note
The client's project and community settings in the TMS must allow for offline translation before you can use these APIs.

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

Info

Polling

It is also possible to poll the GET /task endpoint to see if there are additional tasks to translate but this is not recommended. If your security requirements oblige you to pursue this method, please reach out to support@lingotek.com for more information.

Example API Responses

GET /task

Status

200

cache-control	private, no-cache, no-store, max-age=0, must-revalidate
content-type	application/json
pragma	no-cache

Expand

title	GET Task Response Body

Code Block

language	js

{
  "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

Status

200

cache-control	private, no-cache, no-store, max-age=0, must-revalidate
content-disposition	attachment); filename="article (node): Elit Oppeto Usitas Validus Vicis Zelus.fr_FR.xlf"
content-type	application/x-xliff+offline
pragma	no-cache

Expand

title	GET Task Content Response Body

Code Block

language	js

"<?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

Status

202

cache-control	private, no-cache, no-store, max-age=0, must-revalidate
content-type	application/json
pragma	no-cache

Expand

title	PATCH Task Content Response Body

Code Block

language	js

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

GET /process/{id}

Status

200

cache-control	private, no-cache, no-store, max-age=0, must-revalidate
content-type	application/json
pragma	no-cache

Expand

title	GET Process Response Body

Code Block

language	js

{
  "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}

Status

200

cache-control	private, no-cache, no-store, max-age=0, must-revalidate
content-type	application/json
pragma	no-cache

Expand

title	GET Document By ID and Locale Response Body

Code Block

language	js

{
  "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

community_id	1c5f137b-d9d1-44c3-8ff0-24d0460943bb
complete	true
doc_author_name	j.doe
doc_business_division	text
doc_business_unit	text
doc_campaign_id	text
doc_campaign_rating	0.0
doc_channel	text
doc_contact_email	text
doc_contact_name	text
doc_content_description	text
doc_content_type	txt
doc_cts	1537210928500
doc_domain_type	http://example.com/document
doc_external_application_id	a79ee237-4c69-4126-946d-cf9cfcf13ef1
doc_external_document_id	1
doc_external_style_id	text
doc_mts	1537211244114
doc_purchase_order	text
doc_reference_url	http://example.com/document
doc_region	text
doc_status	COMPLETE
documentId	4222311
document_id	20f93bc9-ed5d-45af-c225-1e4384d73408
locale	fr_FR
locale_code	fr-FR
original_project_id	0
phase_name	translate
progress	100
projectId	70821
project_id	ccc57f52-2f92-418f-b884-8348e95c1be9
status	COMPLETE
targetId	14638015
target_id	db65816a-e854-4b3e-b4f4-9eea10bae34c
type	target

Expand

title	Callback Request Example

Code Block

language	text

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.
GET /task/{id}/content downloads the XLIFF for a given task.

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 "~~dog~~puppy."
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.

Note
If the lgtk:phaseUUID attribute is missing, you will not be able to successfully re-import the XLIFF file.

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.

Tip

Example

'Last Modified' dates for each segment translation will be set in our system based on the upload time. There is no need to add a modified date to a segment.

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

Tip

Example

phase-name="1" might correspond to the following in the header: <phase phase-name="1" process-name="Translate"/>

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.

Tip

Example

Correct: <target...><mrk mtype="seg">This is my translation</mrk></target>

Incorrect: <target...>This <mrk mtype="seg">text</mrk> is translated</target> (Will only import "text")

Incorrect: <target...><mrk mtype="seg">This is one</mrk><mrk mtype="seg">too many mrk tags.</mrk></target>

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.

Info
When you re-import a zip folder of XLIFF files, we ignore the folder structure entirely. We simply use the lgtk:

phaseUUID attribute

phaseUUID attribute in each of the XLIFF files to programmatically match each XLIFF file with the applicable tasks in

our

your Task List.

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

Info

Uploading

Re-importing completed XLIFF files to the TMS has the same effect as if you had worked within

Lingotek's

Enterprise’s Workbench to perform the translations/edits.

Authentication

Via the UI, a user is not able to re-import XLIFF for a task that isn'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
Lingotek
Enterprise.
Authorship is attributed to the user re-importing the tasks through the API.
You can only re-import XLIFF for 'Active' tasks (i.e. tasks
that
that are ready to be worked on, but have not been skipped, canceled or 'marked complete' within
Lingotek
Enterprise).

Effect on the TMS

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

Tip
A revision history for each segment is available

on

in our Workbench.

When
editing, and 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
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; 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 uploaded back to 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 segment is blank upon upload, the TMS will keep the previous translation.

Live Search

spaceKey	PDOC
additional	page excerpt
placeholder	Search documentation

Image Removed Image Removed Image Removed Image Removed Image Removed

Style

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.

On this page:

Table of Contents

Version	Old Version 10	New Version Current
Changes made by	Larry Furr	Kenny Teves
Saved on	Mar 15, 2018	Mar 04, 2024

Content Comparison

Versions Compared

Key

Downloading Tasks

Editing XLIFF files

Uploading A Completed Task

API Diagram

Example API Responses

GET /task

GET /task/{id}/content

PATCH /task/{id}/content

GET /process/{id}

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

Example HTTP Notification

Query Params

Downloading Tasks

Editing XLIFF files

Attributes and metadata

Uploading A Completed Task

Process Completions

File Structure

Authentication

Effect on the TMS