It is possible to integrate translatiostudio into your application, either a CMS, PIM, DAM or else using our REST API.
The integration will consist of 3 parts
| 1 | Your CMS workflow that allows users to send translation requests to translationstudio (this is the actial CMS integration a user can interact with) |
| 2 | Your own simple export API endpoint to allow translationstudio to request the actual translatable json data (POST) |
| 3 | Your own simple import API endpoint to import translatated content into your system again (POST) |
| 4 | An endpoint to query all avaiable CMS languages from (GET) |
| 5 | A simple "ping" endpoint (GET) |
While <1> is exposed to your CMS and users, <2> - <5> are endpoints used by translationstudio to interact with the CMS.
| Your API/integration will have full authoritiy about the data structure and you will receive exactly the same structure to import again. Hence, you need to make sure your export document has everything necessary to import the translation again. |
You may wonder why your API needs to export and import the data itself. translationstudio follows the separation of concerns and since your integration might need updates, you will want to be able to do that yourself instead of waiting for translationstudio to be updated.
1. Understanding the translationstudio workflow
Although the technical details follow, let us assume you have already created a microservice with all necessary parts and your CMS will call your microserive via IFRAME (many headless cms do it that way). This IFRAME will be considered the "workflow interface" for the purpose of this description.
Let us further assume you have added a "plugin" to your CMS that allows the users to access the "workflow interface" in their browser. Your workflow interface will now query available languages from translationstudio (see below) and show its form to let users deceide which languages to translate. Once that is done, the workflow interface will send the actual request to translationstudio. The interface can be closed now.
At a certain point, translationstudio will access your export endpoints to obtain the data to be translated. Some time later, translationstudio will access your import endpoint and provide it with the translated data that need to be imported.
The process is quite simple, so let us dig right into it.
2. Preparations
To get started, you need your own translationstudio application and a license which you can obtain from https://translationstudio.simplidh.tech. You will also need to download the JDK as described in the installation documents at htts://simplidh.tech/translationstudio.
You can deploy your translationstudio application into any folder you like and deploy the license file to the ./conf folder inside your translatinstudio application. During development, you may start translationstudio via console.bat or ./translationstudio console (depending on your operating system).
You can access your translationstudio configuration in your browser at http://localhost:1235 (by default, translationstudio will use the port 1235).
| Some configuration documentation can be found at https://simplidh.tech/translationstudio/ibexa/ibexa.html. |
3. Security Setup
Since security is essential, we will start with this right away. Your integration and translationstudio will need to communicate and security measures are different depending on the type of action.
3.1. Sending a translation request
When your CMS integration wants to send a translation request to translationstudio or query available connector and language combinations, you will need a dedicated access key that you need to create in your translationstudio configuration (similar to https://simplidh.tech/translationstudio/ibexa/ibexa.html#connect-to-your-Ibexa-cms).
When your integration sends any request to the translationstudio application, you will need to include send this key using the request header property Authorization: Bearer {api-key}.
3.2. Receiving a request to export or import data
Whenever translationstudio sends a request to your application, a the request will contain a Authorization: Basic {base64-encoded json} header field. The {base64-encoded json} is a simple json containing the following properties
{
"token": "string",
"stack_id": "string",
"stack_management_token": "string"
}To verify that this request is valid, you need to validate it against https://translationstudio.simplidh.tech/cms/validate and send it as header property Authorization: Bearer {token}. The request will result in a 204 response code if that given token is valid. If so, you may proceed or deny the request otherwise.
The stack_id and stack_management_token are properties to let your integration know which project to connect to and which management key to use.
4. Your CMS Integration
Your CMS integration will need to provide the users with an option to send a translation request to translationstudio. You will need to define source and target language as well as the translation vendor to be used. Luckily, translationstudio can provide you with available options to choose from.
| The rest endpoint https://simplidh.tech/translationstudio/api/rest2/#/Languages/get_languages will provide you with a list of configured language combinations configured by the administrators. Therefore, you may evaluate this list and offer it in your translation workflow. |
A single combination consists of the following properites
{
"id": "string ",
"display-name": "string",
"source-language": "string",
"target-languages": [
"string"
],
"connector-id": "string"
}All you need to do is to offer the display name to your users. However, when you send a translation request to translationstudio, you will need to evaluate the data and send it along. Therefore, let’s have a look at the translation request.
4.1. Understanding a translation request
By default, your workflow will send a translation request to translationstudio via either REST endpoint
INFO: An urgend request will be processed immediately, i.e. content is going to be exported using your export API endpoint. A quota request will store the request and process it later once the configured quota has been reached. The actual payload of your translation request is identical.
{
"project-stack-id": "string",
"user": "string",
"due-date": 0,
"custom-data": [
{
"key": "string",
"value": "string"
}
],
"translations": [
{
"source": "string",
"target": "string",
"connector-project": "string"
}
],
"translatables": [
{
"owner": {
"id": 0,
"uid": "string"
},
"elements": [
{
"id": "string",
"uid": "string",
"display-name": "string",
"version": "string"
}
]
}
]
}
|
identifies your project. Each |
|
may contain the email address to be notified upon translation status change |
|
is the unix timestamp (or |
|
can contain various key-value based information attributes that might be sent to the translators alongside the translatable document. You may send an empty array to ignore this feature (there is no official list of allowed keys as this depends on the 3rd party translation software). |
|
This will contain the actual translation combinations (i.e. which source language should be translated into which target language using the given translation service). A list of available combinations can be obtained using the |
|
This array contains the actual elements you want to be translated. If you want to translate a single page, the array will contain exactly 1 entry. |
| The rest endpoint https://simplidh.tech/translationstudio/api/rest2/#/Languages/get_languages will provide you with a list of configured language combinations configured by the administrators. Therefore, you may evaluate this list and offer it in your translation workflow. |
The translatables array may seem a bit comlicated at first, but it really is not. Let’s take a closer look.
owner is used to simply identify the page in your system and it can be undertood as the "owner" of all the content you want to translate (a web page, for example). This property contains 2 attributes:
. id (numeric)
. uid (string)
Depending on your system, elements might be identified using numeric ids or string-based unique identifiers. If you do not need the numeric id, please set it to 0. *If you do not need the uid, please also set it to a string version of your id
elements contains the list of elements you actually want to translate. Depending on your system, a "page" might contain a various number of sections/templates of a single entry (like headless CMS, typically).
id and uid identify the actual element (see owner for details on how to use those attributes).
display-name is the meaningful name of the element you want to translate (the section element)
version is an optional field you may need depending on your system.
You will make use of id and uid, so please ignore id-target and uid-target. Those attributes are necessary in other CMS but not in yours.
|
INFO: If your request was successful, you will receive a 200 response code.
4.2. Demo Project
You can use our demo project to start implementing your own integration: https://bitbucket.org/i-dmedia/cms-integration-demo-project/src/main/
5. Creating and importing translatable content
Your export API endpoint will receive evey information necessary to create a translatable document (either in JSON or XML format). If you create a JSON format, this will be converted into XML automatically.
| See security section for information on how to secure your integration. |
5.1. Providing translatable data
Once translationstudio processes your translation request to create translatable XMLs, your export API endpoint will receive a POST request with the following payload (in addition to stack and management tokens in your authorization header):
"entry_uid": "element uid"
"locale": "source locale"
"version": 0Your produced JSON needs to contain at least the follwing elements
[
{
"field": "blt48347c2cf021ab31.title",
"translatableValue": [
"Hello",
"World"
]
},
{
"field": "blt48347c2cf021ab31.design.inscription",
"translatableValue": [
{
"field": "",
"children": [
{
"text": "Hello."
},
{
"text": "How are you?"
},
{
"text": "Well, I hope."
}
]
}
]
}
]The field property denotes the content element in your system. The translatableValue array contains the translatable content. It may either be an array of strings or contain elements of the format
{
"children": [
{
"text": "This is translatable text."
}
]
}| Your objects and response JSON may also contain additional fields if needed. The translatable content will be extracted from the fields above and the rest will be kept "as is". |
5.2. Importing translated content
Your import API endpoint will receive a POST request with the exact same strucuted json element your export API endpoint has created. Of course, the translatable text will have been replaced by the translated content.
| since you will only receive your json object, make sure you provide all necessary information in it during the export process (such as the entry id). |
5.3. Available languages
Your GET endpoint may provide a list of available CMS languages. These will be stored as a key-value pair in a json object:
{
"code": "string"
}The code is the language abbreviation used by the CMS and its value is the display name used in the translationstudio configuration.
If no languages are available, please provide an empty object { }.
|
6. Useful Resources
Please check out
It goes without saying, but translationstudio has a lot more to offer and can be customised in many different ways. If you are interested in more information, let us talk. See https://idmedia.com for contact information.