Overview

This document helps you jumpstart your translation integration using the GlobalLink Connect Cloud (GCC) REST API. As a first step, you would require a Sandbox GlobalLink Connect Cloud account. Contact your GlobalLink representative to get your account setup.

Architecture

Content systems can leverage the translation workflow capabilities of GlobalLink and offer the possibility of translating content from within their user interface. This is usually achieved by developing a custom plugin/extension to these systems, which manages the translation data exchange with GlobalLink using REST. Business users can then initiate and track the translation progress within their content system. A typical content integration architecture use a push-poll mechanism to exchange data for translation with GlobalLink Connect is explained below.

  1. The GlobalLink plugin is an extension to the client content system and provides the capabilities to send and receive content for translation. Business users can select the items (pages/products/articles etc.) that they want translated and start a translation submission.
  2. You specify the desired target languages and a due date by when they want the translations delivered back. The plugin identifies the selected items and serializes the translatable content to a XML data stream, which is sent to GlobalLink Connect using the REST API.
  3. A real time status report of the translation requests is made available to the business users with the ability to filter on various criteria such as status, language etc.
  4. Project Managers and Linguists work within GlobalLink to execute the translation workflow which typically includes translation, review and proofreading. On completion of the translation workflow, the translated content is available in GlobalLink Connect with status Completed.
  5. The Add-On plugin polls GlobalLink Connect to retrieve the translated content and merge the translations back into the content management system. This functionality is usually developed as a scheduled service, which can be configured to poll GlobalLink Connect at a pre-defined interval.

Terminology

Key terminology of GlobalLink Connect Cloud is defined below.

Term Definition

Session

A user authenticated session is generated which allows users to authenticate each API request. Default session timeout is 30 minutes, but can be configured independently for each organization.

Connector

A connector defines all the configurations for accepting and processing a translation request. There are two types of connectors:

  • API based: where the content to be translated resides in the cloud and is accessible over a REST API. In such cases, it is only a list of content identifiers that is submitted to the API
  • Data based: where the content to be translated is actually sent to GlobalLink as a part of the payload over the REST API

Content

A content object that needs to be translated. While integrating with other content systems, this is usually a XML file with a key-value schema that is exported from the original content system.

Context

A standalone HTML rendering of the content with all supporting images, CSS etc., which can be used to generate an in-context preview of the translations.

Submission

A submission is a translation request for multiple content objects into one or more target languages.

Job

A job is a collection of all tasks within a submission for a specific language. For example, if a submission is created for 5 documents to be translated to five languages, it generates five jobs, one each for the five languages with five tasks (one for each document).

Task

A task is generated for each translation request for a content object in a specific target language. For example, if a submission is created for five documents into five languages, it generates 25 tasks.

APIs

When using the GCC API:

API Endpoint Description

Authentication

/session

GlobalLink APIs use bearer authentication. The Authentication API provides the access token to authenticate API calls. The access token needs to be included in the header of every request.

Connector Configuration

/connectors

The connectors API allows you to get the list of configured connectors along with all their configuration details such as configured language directions, file formats and submission configuration options.

Content

/content

The content API allows you to upload files, reference files or binary (base64) data for translation.

Context

/context

The context API allows you to submit a complete standalone HTML rendering of the content for which translation is requested. This is then used for doing in-context reviews of the translations before the final translations are delivered back to the content repository.

Submission

/submissions

The Submissions API allows you to create a translation request for one or more content objects by specifying the source locale, list of target locales, due date, translation instructions and a bunch of other configurations as applicable, depending on the connector configuration.

Jobs

/jobs

The jobs API allows you to query the list of jobs filtered by various criteria. You can also perform actions on the job such as approve,cancel etc based on the state.

Tasks

/tasks

The Tasks API allows you to query the list of jobs filtered by various criteria. You can also perform actions on the job such as approve,cancel etc based on the state.

  • All paths are prefixed
  • All data sent to non-GET endpoints is in the JSON format
  • All responses are in the JSON format

Initialize

Before you begin making calls to the API you need to initialize a session and get the list of configured connectors for your account.

  1. To start your session, make a POST request to /session/start by passing the username and password parameters to get a session-token.
    curl -X POST https://connect-dev.translations.com/api/v2/session/start -H 'Cache-Control: no-cache' -H 'Content-Type: application/json' -d '{\"username\":\"test\",\"password\":\"test\"}'
  2. To get the list of configured connectors, make a GET request to /connectors endpoint passing the session-token in the header
    CURL -X GET https://connect-dev.translations.com/api/v2/connectors -H 'Authorization: Bearer n3BAdQlxUt4xHQ3' -H 'Cache-Control: no-cache'
  3. To get the connector configuration such as list of locales and configured file types, make a GET request to /connectors/config passing the session-token and connector-key in the header.
    CURL -X GET  https://connect-dev.translations.com/api/v2/connectors/config -H 'Authorization: Bearer n3BAdQlxUt4xHQ3'  -H 'Cache-Control: no-cache' -H 'connector_key: 2ed16ebb0abdfd83dae6c68b92af3c97'

The response to the above calls give you all the configuration details needed to make a translation request. Next, let's create a new Submission.

Submit (Data)

For integration with any typical content repository, the most commonly used method is to submit data. In this case, an add-on or a plugin is built within the content system which is responsible for reading the content and generating a translatable payload data that can be sent over to GlobalLink Connect. You also have the possibility of capturing the HTML context and sending that over to GlobalLink Connect using the context API.

Upload Context

If the files you are uploading have an HTML context, you can upload additional context information. For example, an e-commerce product has an HTML page with rendered product data. The contextual information is used to preview and edit translations in GlobalLink.

To upload context, call one of the following endpoints :

  • /context/html : to upload a single standalone HTML file
  • /context/zip : To upload a standalone ZIP with HTML, stylesheets, and images.
  • /context/xslt : to upload a XML which will be transformed using XSL to generate a preview page.

The response to the above calls provides a context URL that you can use in your next call to upload the translatable content to GlobalLink Connect.

Upload Content for Translation

To upload a file for translation:

  1. Call the /content/file endpoint and specify the connector_key, name, and file_type. If you have uploaded context, you can also specify the context URL in the context_url parameter.

    The response provides a content_id that will be used in the next request.

  2. Repeat the first step to upload as many files as you want and store all content IDs in a temporary array within your client for each file requiring translation.

    If the option of storing an array of content IDs is not possible, you can call the /content endpoint to get a list of content IDs that were previously submitted.

Upload Reference

  1. If you need to upload reference files like style-guides or published PDFs, you can use the /content/reference endpoint to upload those.

Create a Submission

The Upload Content and Upload Reference calls will return content IDs. You can group multiple requests together into a single submission by specifying an array of the content IDs that need to be included in the /submission/submit call.

To create a translation job:

  1. Call the /submissions/submit endpoint.
  2. Specify the source_locale, target_locale,due date,submission name and the list of content IDs to include in the translation job.

The response provides a submission_id that you can use to track future status updates and requests.

Once a Submission is started, it progresses through a state based workflow and you can query for the status based on various filter parameters. Once started, you can call the /submissions endpoint and pass the submission_ID to get the status of the submission

Retrieve Translated Content

Once the content is translated in GlobalLink Connect, the submission, job and all tasks are in the Completed step. There are two ways to retrieve the translated content.

Polling

This is the most commonly used method, wherein the client system polls GlobalLink Connect on a regular basis to check for completed jobs. This requires implementation of a scheduled polling agent on the client's system to execute the flow below.

  1. Call the /jobs endpoint with status=completed to get a list of completed jobs.
    curl -X POST https://connect-dev.translations.com/api/v2/jobs -H 'Cache-Control: no-cache' -H 'Content-Type: application/json' -H 'Authorization: Bearer T4xISXP66mQJhy3' -H 'connector_key: 2ed16ebb0abdfd83dae6c68b92af3c97' -d '{\"status\":\"completed\"}'

    The response provides all Job IDs with Complete status for the specified connector.

  2. For each job in the above list, get a list of tasks by calling /jobs/task endpoint with the job-id parameter as below.
    CURL -X GET 'https://connect-dev.translations.com/api/v2/jobs/tasks?job_id=1512644365426' -H 'Authorization: Bearer mhNUiAKtmIAYNgI' -H 'Cache-Control: no-cache' -H 'Content-Type: application/json' -H 'client_secret_key: 2ed16ebb0abdfd83dae6c68b92af3c97'
  3. For each task in the job, download the translated file by calling the /tasks/download and specifying the task ID.

    Your translated files are downloaded in the response.

    curl -X GET 'https://connect-dev.translations.com/api/v2/tasks/download?task_id=1529316546902' -H 'Authorization: Bearer T4xISXP66mQJhy3' -H 'Cache-Control: no-cache' -H 'Content-Type: application/json' -H 'client_secret_key: 2ed16ebb0abdfd83dae6c68b92af3c97'
  4. Once the translated file is downloaded, call the /tasks/confirm endpoint to mark the task as delivered.
    curl -X POST 'https://connect-dev.translations.com/api/v2/tasks/confirm -H 'Authorization: Bearer T4xISXP66mQJhy3' -H 'Cache-Control: no-cache' -H 'Content-Type: application/json' -H 'client_secret_key: 2ed16ebb0abdfd83dae6c68b92af3c97' -d '{\"task_id\": 1XXXXXXXXXXX7}

State Flow

The illustration below explains the state flow for a typical translation request.

  1. Pre-Process: In this stage, the system is processing the received data and preparing the submission,job and tasks in Connect Cloud.
  2. Started: The submission progresses to this state once the translation workflow has started in Project Director.
  3. Analysed: The first step that runs on the files is a TM analysis. This state indicates that the submission has been analyzed and is ready for Translation production.
  4. Approval: This is an optional state that can be enabled for your connectors, if you want business users to approve every submission before it goes to production. Users can validate the word counts at this stage.
  5. Translate: This state indicates that the submission is being translated by our translators.
  6. Completed: Once all translation is complete, the job is in the complete state. The Submission moves to "Complete" state, after all its jobs are complete.
  7. Delivered: Upon successful confirmation, all jobs and submissions move to the "Delivered" state.

WebHooks

A WebHook is an HTTP POST that occurs when a certain event occurs within the GlobalLink Connect workflow.

GlobalLink Connect has the capability of emitting callbacks for specific events such as completion and cancellation of a job. In such a case, the callback URL needs to be specified at the time of submission creation. Upon completion of the job, a POST request is made to the callback URL with the payload containing information about the job that was completed.

For more details on the WebHook callbacks, refer to Callback Handler in the documentation. Each customer can implement their own business logic in the callback handling, but the most typical flow is explained below.

The curl examples for Download and Confirm are same as the ones listed in the Polling section.

The list of events that emit a callback are:

  1. Anaylzed
  2. Submission Complete
  3. Job Completed
  4. Submission Delivered
  5. Job Delivered
  6. Submission Cancelled
  7. Job Cancelled

Sample JSON

Analysed

This event would be triggered when content analysis is completed for wordcount details


{
  "hit_time": 1548339958037,
  "data": {
	"type": "Analyzed",
	"scope": "submission",
	"submission": {
	  "submission_id": 1548339758201,
	  "submission_name": "Marcus Sub",
	  "submitter": "",
	  "created_at": 1548339758201,
	  "attributes": {}
	},
	"language_wordcounts": [
	  {
		"target_locale_details": {
		  "connector_locale": "fr-FR",
		  "pd_locale": "fr-FR",
		  "locale_label": "French"
		},
		"wordcount_details": [
		  {
			"count": 0,
			"key": "noMatch",
			"display_name": "No-Match"
		  },
		  {
			"count": 0,
			"key": "fuzzy",
			"display_name": "Fuzzy"
		  },
		  {
			"count": 0,
			"key": "oneHundredPercent",
			"display_name": "100% Match"
		  },
		  {
			"count": 0,
			"key": "gold",
			"display_name": "Gold"
		  },
		  {
			"count": 0,
			"key": "repetitions",
			"display_name": "Repetitions"
		  },
		  {
			"count": 0,
			"key": "total",
			"display_name": "Total"
		  }
		]
	  },
	  {
		"target_locale_details": {
		  "connector_locale": "de-DE",
		  "pd_locale": "de-DE",
		  "locale_label": "German"
		},
		"wordcount_details": [
		  {
			"count": 0,
			"key": "noMatch",
			"display_name": "No-Match"
		  },
		  {
			"count": 0,
			"key": "fuzzy",
			"display_name": "Fuzzy"
		  },
		  {
			"count": 0,
			"key": "oneHundredPercent",
			"display_name": "100% Match"
		  },
		  {
			"count": 0,
			"key": "gold",
			"display_name": "Gold"
		  },
		  {
			"count": 0,
			"key": "repetitions",
			"display_name": "Repetitions"
		  },
		  {
			"count": 0,
			"key": "total",
			"display_name": "Total"
		  }
		]
	  }
	]
  }
}
		

Submission Complete

This event would be triggered when submission is completed and available for download.

{
  "hit_time": 1548340134008,
  "data": {
	"type": "Completed",
	"scope": "submission",
	"submission": {
	  "submission_id": 1548339758201,
	  "submission_name": "Jason",
	  "submitter": "",
	  "created_at": 1548339758201,
	  "attributes": {}
	}
  }
}
			

Job Complete

This event would be triggered when langauge level job is completed and available for download.

{
  "hit_time": 1547559113338,
  "data": {
    "type": "Completed",
    "scope": "job",
    "submission": {
      "submission_id": 1547558826709,
      "submission_name": "a_postman_multiple_007",
      "submitter": "",
      "created_at": 1547558826816,
      "attributes": {}
    },
    "locale": {
      "connector_locale": "fr-FR",
      "pd_locale": "fr-FR",
      "locale_display_name": "French"
    }
  }
}


			

Submission Delivered

This event would be triggered when language level job is confirmed as delivered.

{
  "hit_time": 1547502525727,
  "data": {
    "type": "Delivered",
    "scope": "submission",
    "submission": {
      "submission_id": 1548339758201,
      "submission_name": "New Job",
      "submitter": "",
      "created_at": 1548339758259,
      "attributes": {}
    }
  }
}
			

Job Delivered

This event would be triggered when language level job is confirmed as delivered.

{
  "hit_time": 1548361110393,
  "data": {
    "type": "Delivered",
    "scope": "job",
    "submission": {
      "submission_id": 1548339758201,
      "submission_name": "New Job",
      "submitter": "",
      "created_at": 1548339758259,
      "attributes": {}
    },
    "locale": {
      "connector_locale": "de-DE",
      "pd_locale": "de-DE",
      "locale_display_name": "German"
    }
  }
}
			

Submission Cancelled

This event would be triggered when submission is cancelled.

			

{
  "hit_time": 1548360466331,
  "data": {
    "type": "Cancelled",
    "scope": "submission",
    "submission": {
      "submission_id": 1548103102729,
      "submission_name": "Grey",
      "submitter": "",
      "created_at": 1548103102730,
      "attributes": {}
    }
  }
}
			

Job Cancelled

This event would be triggered when lanaguage level job is cancelled.

			

{
  "hit_time": 1548360465939,
  "data": {
    "type": "Cancelled",
    "scope": "job",
    "submission": {
      "submission_id": 1548103102729,
      "submission_name": "Greary",
      "submitter": "",
      "created_at": 1548103102780,
      "attributes": {}
    },
    "locale": {
      "connector_locale": "fr-FR",
      "pd_locale": "fr-FR",
      "locale_display_name": "French"
    }
  }
}