Overview
The STREAM API was developed to provide you with a one stop, state of the art localisation management service. The API was designed to promote an easy to use, and accessible resource for managing your translations as an external service, using the the latest connectivity technologies and security protocols..
Typically, you'll use the STREAM API because you want to send content to be translated by TranslateMedia, for example a document, or some product information from a PIM or CMS. The API contains many features to help track the jobs in progress, and to retrieve the translated content using a multitude of mechanisms.
Before you start using the STREAM API, we recommend that you become with the basic data constructs that are used and the processes that govern the workflow.The API supports webhooks as a useful manner to trigger processes from external services.
Here is a brief summary of how it works:
All translation work is organised in a project, as the top level entity. The content to be translated is defined in the project as a set of one or more keys. The actual work to be performed is defined as a task or set of tasks, whereby you describe the keys to be translated, the languages, and the type of service desired. There is more too - you can also define events and triggers that govern how and when you wish the work to be executed, and how would the completed translations to be delivered back.
In essence, the API allows you to define every aspect of your project within a single payload, or by building it incrementally using the functions provided.
Here is a more indepth description of the operation and some definitions:
Authentication:
Before you can do anything with the STREAM API, you will need to authenticate it by using the credentials provided. See here for more information on the authentication process and how to obtain credentials.
Projects:
All translation work is organised within a project. Therefore a project can be thought of as the top level container used to interact with the API.
If you want anything translated, you need to first create a project (after authentication of course). It can be useful to store the reference of the project(s) you have created in order to keep track of work in progress, although it is always possible to retrieve a list of project references from the API in case you have not.
Projects have an associated status. This indicates the current stage of the project in the overall workflow.
All statuses are automatically tracked and updated by our internal systems. The transition from "open" to "quoting" is the only acepted update via the API.
The list of status is the following:
-
open
This is the default status for any new project. An open project can be ammended by adding or updating its tasks, languages, keys or any other relevant item.
An open project has no quote and/or jobs associated to it.
If a project status is "open" you can transition it to "quoting" to request the calculation of a quote for that project. For more information look at our api
documentation page.
-
quoting
A project with a "quoting" status means that a quote has been requested for the project content and it is currently calculating.
As soon as the calculation is finished, a quote will be available for the project and the status will automatically be updated to "quoted".
-
quoted
A project with a "quoted" status means that a quote has been calculated and is pending approval or rejection.
If any triggers have been configured, the quote will be delivered by the chosen delivery method. The quote can also be approved or rejected via our corporate portal.
-
processing
A project with a "processing" status means that a quote has been approved and an order has been created.
That order is currently being processed (translated/revised). As soon as the order is completed the status will be automatically updated to "closed"
-
rejected
A project with a "rejected" status means that a quote has been calculated but it has been rejected by the client.
No further processing will occur on these projects.
-
closed
A project with a "closed" status means that a quote has been approved and all the processing has been done and the final output was delivered to the client.
Keys:
Keys represent the content to be translated. Keys are defined within the project as key value pairs. You need at least one key in the project (in order to have something worth translating), or you can have thousands of keys if your project is complex. A key can be a simple text string, or a complete document stored as a binary string. The system of keys is a versatile and standardised way of representing content in any format.
Tasks:
Once there is a project containing some keys, the next step is to describe the work that must be performed. You do this by defining one or several tasks. A task will typically refer to a number of the keys, the language pairs for the translation, and the service you require. Services are typically variants of translation services, for example with or without revision, machine translation, transcreation, etc. For a full list of services offered, see the 'Get quote types' request on the 'Quote' section on the
documentation.
The full list of services is:
-
Draft
A quick translation carried out by a single linguist, without a revision stage.
Ideal for content that’s not consumer-facing, intended for internal use or to get a quick, general understanding of content.
-
DraftExpress
A quick translation carried out by a single linguist, without a revision stage.
Ideal for content that’s not consumer-facing, intended for internal use or to get a quick, general understanding of content.
Fast turnaround.
-
Professional
Native, human translation followed by professional revision, editing and QA by another linguist.
Best for Informative content where maintaining style and brand tone of voice is essential.
-
ProfessionalExpress
Native, human translation followed by professional revision, editing and Q by another linguist.
Best for Informative content where maintaining style and brand tone of voice is essential.
Fast turnaround.
-
MachineTranslation
Raw, unedited translation produced by a machine and processed in our secure environment.
Ideal for rapid translation of content at scale - best for highly standardised content that’s not critical to success and doesn’t require creative input.
-
MachineTranslationWithRevision
Machine translation, improved through subsequent human editing and machine learning.
Best for consumer-facing content where style and tone of voice are not critical.
-
MachineTranslationWithRevisionExpress
Machine translation, improved through subsequent human editing and machine learning.
Best for consumer-facing content where style and tone of voice are not critical.
Fast turnaround.
-
PEMTWithRevision
Machine translation, improved through subsequent human editing and machine learning, with an additional proofreading round.
Best for consumer-facing content that needs to be tailored to your brand's tone of voice and style.
-
PEMTWithRevisionExpress
Machine translation, improved through subsequent human editing and machine learning, with an additional proofreading round.
Best for consumer-facing content that needs to be tailored to your brand's tone of voice and style.
Fast turnaround.
-
Transcreation
Adaptation of source materials by marketing and advertising linguists to produce a translation that captures the desired persuasive or emotive effect of the original message.
Ideal for creative brand work, performance marketing and advertising campaigns.
-
TranscreationExpress
Adaptation of source materials by marketing and advertising linguists to produce a translation that captures the desired persuasive or emotive effect of the original message.
Ideal for creative brand work, performance marketing and advertising campaigns.
Fast turnaround.
-
TranscreationWithRevision
Adaptation of source materials by marketing and advertising linguists to produce a translation that captures the desired persuasive or emotive effect of the original message, made even more compelling by the addition of a second linguist.
Ideal for creative brand work, performance marketing and advertising campaigns.
-
TranscreationWithRevisionExpress
Adaptation of source materials by marketing and advertising linguists to produce a translation that captures the desired persuasive or emotive effect of the original message, made even more compelling by the addition of a second linguist.
Ideal for creative brand work, performance marketing and advertising campaigns.
Fast turnaround.
-
OfflineJob
Uase this setting to request a manual quote for any other linguistic function not covered by the above list.
Triggers:
We use triggers to schedule the moment when the tasks can be actually executed and performed. For example, you may construct a project but specify that you want it to begin at 17:00 the next day, or, if you are incrementally adding tasks to a project, you may specify to start the work once the total wordcount has reached 5,000 words.
Events:
Events are a powerful way to control when certain actions are performed.
Events can be used to notify external systems whenever there is a change in project status/progress.
The full list of events is:
-
project.task.translation.language.completed
Event fired when one of the languages in a translation task is completed and ready for delivery.
-
project.task.translation.completed
Event fired when all the languages in a translation task are completed and ready for delivery.
-
project.completed
Event fired when all the tasks in a project have been completed and the full project is ready for delivery.
-
quote.ready
Event fired when the calculation of a quote for a project has finished and the quote is ready for approval.
Different actions can be configured for when an event is fired. The different types available are:
-
email
An email will be sent to the configured recipents.
-
ftp
A file will be uploaded to the configured ftp server
-
webhook
An external API will be notified of the event
For more information on how to use events see the Events section on our
documentation page
And the parameters to supply are essentially the following:
Source language:
The source language is described for each key by a language code. For a full list of source languages supported and their associated codes, see here.
Target language:
The target language is described in the task by a language code. For a full list of languages supported and their associated codes, see here.
Specialism:
We categorised content in a number of specialisms related to the subject matter, for example, medical, legal, technical, marketing, etc.
The specialism is defined alongside the source language against each key. If no specialism is included, it will default to general. For a full list of specialisms supported, see here.
Context:
(images, descriptions, etc.)
Start
The best way to get started with the STREAM API is to obtain API CREDENTIALS and start experimenting the API, using our Sandbox testing envirnoment. To obtain an API Key,
you will need to login and go to the API Key inside of your portal page. If you are not yet registered with TranslateMedia, please register yourself by clicking here.
Your API Credentials should look similiar to the example below. Please note that your API Credentials must be kept private.
| Client Id: |
{{ ClientId }} |
| Client Secret: |
{{ ClientSecret }} |
The STREAM API is implemented as a
RESTful Api service that uses
OAuth 2.0 authorisation/authentication
In order to initially test our API, we provide a sandbox endpoint, which serves as a testing environment. Before using the live API, we strongly suggest that you start by
testing your code against the sandbox environment. You can find the STREAM API sandbox services at:
https://apitest.toppandigital.com/
When you are ready to start using the live endpoint, STREAM API live services are available at:
https://api.toppandigital.com/
