intercontact translations has been helping companies communicate more successfully since 1991. What makes us different from others on the market? Our passion, sophisticated language technologies and high standards of quality.
This short guide is a starting point to connect your application or translation workload to intercontact’s Translation API.
Full documentation with examples for all calls is available at https://api.inter-contact.de/api-docs/.
The InterTMS Translation API can be used to digitally retrieve and transmit translations to intercontact.
It is based on the REST standard for HTTP-API’s which is the standard predominantly used to exchange data between machines. It is easy for people to read and minimizes the transmition overhead.
The following chapters will give any developer a basic understanding of how to send translatable text and retrieve the final translation afterwards.
The InterTMS is a closed API. In order To get started with automated translation workflows, you should first get in contact with the sales team. You can reach out to them via e-mail (order@inter-contact.de) or by phone. Check out https://www.inter-contact.de for more information.
We will describe the important endpoints and entities in this section.
A projectDefinition is a pre defined project definition. It will describe the properties of the text you send to us. This could be used e.g. for identifying machine translation text vs. human translation text or any other special requirements for your specific use case. We will provide you with this information beforehand.
A translationJob contains translationUnits. You can add as many translationUnits to a TranslationJob as you like. It helps to group logical linked translationUnits to a logical unit. You also need to define the source language and the requested target languages at this stage.
A translationUnit is a logical part of your translation content. This could be e.g. a product name, product description, page content or any other content. The source text can be provided as plain text or HTML format. Keep in mind that the maximum text length is 500,000 characters. It is possible to assign an identifier to each translationUnit. This could be helpful for later identification and matching for the import process. This identifier needs to be smaller than 255 characters.
The API is secured with a technique called JSON Web Token (JWT). It utilizes the standard authorization header using the Bearer scheme. Example: “Bearer {token}”. The intercontact Translation API is secured with the JSON Web Token industry standard (RFC 7519). Each customer is provided with an individual user account to request a short lived bearer token which must be implemented in the authorization header. You can get an access token from the authorization endpoint located at https://identity.inter-contact.de/connect/token for the live environment or at https://identity.sandbox.int er-contact.de/connect/token for the sandbox environment. The oauth2 authentication flow has to be “grant_type”=“password”. The corresponding client has to be “client_id”=“CustomerAPI”. You can find a full documentation of JWT-tokens and how they work here: https://jwt.io/introduction/
https://identity.sandbox.inter-contact.de/connect/token
OR
https://identity.inter-contact.de/connect/token
{
"grant_type": "password"
"username": "%USERNAME%"
"password": "%PASSWORD%"
}
Content-Type: application/x-www-form-urlencoded
{"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c","expires_in":3600,"token_type":"Bearer","scope":"openid profile roles"}
This is the first endpoint in the process of transmitting translatable text to intercontact. It returns an Identifier which is necessary for the next API calls. In this endpoint you define a collection like entity which you can then fill with translationUnit’s.
{
"foreignIdentifier": "ProductId:80",
"targetLanguages": [
"en-GB",
"nl-NL"
],
"sourceLanguage": "de-DE",
"projectDefinition": "33BA86CD-D0DD-4B92-DCF9-08D9DCD21C67"
}
This endpoint will return the translationJob ID. This is necessary to submit the actual translations in the next step!
c4defabc-1301-4297-8715-8fdfbc0b716a
This is the endpoint used to submit the actual translations to intercontact. This call can be called multiple times depending on your use case and data structure.
{
"sourceText":
{
"text": "T-Shirt blau",
"language": "de-DE"
},
"externalId": "ProductId:80:Title",
"jobId": "c4defabc-1301-4297-8715-8fdfbc0b716a",
"targetLanguages":
[
"en-GB",
"nl-NL"
]
}
This endpoint will return the created translationUnit ID.
f7ff91e1-4179-4d6a-bbc8-378030250489
When all translationUnit’s have been transmitted to intercontact, the next step to get the translationJob translated, is to mark the created translationJob as ready for translation. This action cannot be reverted. After setting the translationJob to the ready state, no changes can be made to that particular translationJob and it’s translationUnit’s.
It is possible to monitor the status of the translationJob. When the translationJob’s state has been changed to Translated, you can get all translationUnits of this specific translationJob. You could, fo example, fetch the status periodically every 5 minutes until the translation is finished.
In this scenario we would send a Webhook to an API endpoint provided by you.
The POST payload looks like this:
{
"jobId": "c4defabc-1301-4297-8715-8fdfbc0b716a",
"projectDefinitionId": "33BA86CD-D0DD-4B92-DCF9-08D9DCD21C67",
"webhookEvent": "TranslationJob_Delivered"
}
The pre-defined secret is included in the request header “X-Secret”. Please check this secret before starting any action!
After receiving this webhook, you can poll the results once.