Intento Integration Guidelines for TMS scenarios

Overview

This guide will help you build a lightweight connector to Intento. It is helpful for developers who want to integrate Intento with a Translation Management System (TMS) to translate files or segments.

A typical lightweight TMS connector will feature the following items:

• A configuration page where the user can enter the API key to connect their Intento account

• A way to choose Smart Routing when requesting machine translation. This can be an actionable trigger in the TMS UI at the Project or Project template level, or a configuration option in the connector configuration page.

Configuration flow

1. Fetch available Smart Routings

2. Fetch the Language Pairs available for the selected Smart Routing

3. Ensure the selected source and target languages pair is available via the selected Smart Routing.

Translation flow

1. Collect all the segments that require translation.

2. Submit segments to translation via Asynchronous API by providing:

   1. Language pair

   2. Smart Routing

   3. Segments or xliff file to translate

3. Use a long-polling technique to check the translation status

4. Once the translation is done, get results and populate them in the project

Authentication

Intento uses API Key authentication. Every request sent to the Intento API should have a header apikey with a specified key that can be obtained from the console. 

Usage tracking

Intento uses User-Agent to determine which application uses the API and allows customers to track the volume translated via the connector. Every request sent to the Intento API should have a User-Agent with the value Intento.Integration.<Connector Name>/version

Supported Languages

To get the list of all supported languages, send a request:

curl -H 'apikey: <APIKEY>' -H 'User-Agent: Intento.Integration.<CONNECTOR_NAME>/version' 'https://api.inten.to/ai/text/translate/languages'

Response:

[
    {
        "direction": "left-to-right",
        "intento_code": "af",
        "iso_name": "Afrikaans"
    },
    ...
]

Smart Routings

Intento uses Smart Routings and Language Pairs to identify the workflow that maximises the translation quality by following customer requirements.

List of available Smart Routings

To get the list of the available Smart Routings, send the following request: 

curl -X 'GET' \
  'https://api.inten.to/routing-designer/?visibility=all' \
  -H 'accept: application/json' \
  -H 'apikey: <APIKEY>' \
  -H 'User-Agent: Intento.Integration.<CONNECTOR_NAME>/version'

Response:

{
  "data": [
    {
      "rt_id": 1,
      "name": "best",
      "description": "Intento routing for the General domain",
      "updated_at": "2024-12-18T14:07:43.171Z",
      "updated_by": "04ebba4b-d03f-418d-9593-97e699f21a63",
      "is_public": true,
      "is_active": true,
      "is_allowed": true
    },
    ....
    ],
  "total": 35
}

 

List of available Language pairs

Each Smart Routing has a set of rules containing language pairs that are available for translation. To get a list of the available rules, send a request:

curl -X 'GET' \
  'https://api.inten.to/routing-designer/<rt_id>' \
  -H 'accept: application/json' \
  -H 'apikey: <APIKEY>' \
  -H 'User-Agent: Intento.Integration.<CONNECTOR_NAME>/version'

Response:

{
  "rt_id": 1390,
  "name": "intento_gen_ai_routing_web_demo",
  "description": "GenAI custom routing for Intento Demo Organization",
  "updated_by": "62eac193-7cda-4e8c-bc5a-b02a65d97197",
  "updated_at": "2025-01-16T17:19:31.983Z",
  "is_active": true,
  "is_public": false,
  "rule_groups": [
    {
      "rule_group_id": 21647,
      "from": "en",
      "to": "es",
      "provider": "ai.text.translate.google.translate_api.v3",
      "failover": [],
      "glossary": [],
      "processing": [],
      "updated_at": "2025-01-16T17:19:27.582Z",
      "updated_by": "62eac193-7cda-4e8c-bc5a-b02a65d97197"
    },
    .....
  ]
}

Translation

To promptly translate large amounts of text, use an asynchronous call to the Intento API. Send all segments in one batch or xliff file in asynchronous mode, and the API would split them into chunks, perform multiple translation calls with the provider, assemble the response, and return the translation result in one batch.

Submit Segments Translation

To submit a translation request with an array of segments, post the following request:

curl --location 'https://api.inten.to/ai/text/translate' \
--header 'Content-Type: application/json' \
--header 'apikey: <YOUR_API_KEY>' \
--header 'User-Agent: <Intento.Integration.<CONNECTOR_NAME>/version>' \
--data '{
    "context": {
        "text": [
            "Large text corpus",
            "of text to translate"
        ],
        "to": "es",
        "from": "en"
    },
    "service": {
    "routing": "best",
    "async": true
    }
}'

Submit Xliff Translation

To submit a translation request with an Xliff file, post the following request:

curl --location 'https://api.inten.to/ai/text/translate' \
--header 'Content-Type: application/json' \
--header 'apikey: <YOUR_API_KEY>' \
--header 'User-Agent: <Intento.Integration.<CONNECTOR_NAME>/version>' \
--data '{
    "context": {
        "text": "<XLIFF CONTENT>",
        "to": "es",
        "from": "en",
        "format": "xliff-2.0"
    },
    "service": {
      "routing": "best",
      "async": true
    }
}'

Response:

{"id": "80fab22b-f999-421f-9ac4-c0b7e55a2158"}

The response contains the ID of the operation (please note that the ID value here is just an example and will differ from the ID you’d receive in response)

Get Translation Results

To retrieve the result of the operation, make a request:

curl --location 'https://api.inten.to/operations/80fab22b-f999-421f-9ac4-c0b7e55a2158' \
--header 'apikey: <YOUR_API_KEY>​' \
--header 'User-Agent: <Intento.Integration.<CONNECTOR_NAME>/version>'

We recommend checking for operation completeness approximately once a second. You should see the following response while the request is incomplete:

{
    "done": false,
    "error": null,
    "id": "80fab22b-f999-421f-9ac4-c0b7e55a2158",
    "meta": {},
    "response": []
}

Once the operation is complete, the service returns the translated text:

{
    "id": "80fab22b-f999-421f-9ac4-c0b7e55a2158",
    "done": true,
    "response": [
     {
      "results": [
        "Corpus de texto grande",
        "de texto a traducir"
      ],
      "meta": {
      "detected_source_language": [
        "en",
        "en"
      ],
      "size_info": {
        "symbols": 37,
        "provider_symbols": 37
      },
      "routing": {
        "id": "best"
      },
      "client_key_label": "production"
    },
    "service": {
      "provider": {
      "id": "ai.text.translate.amazon.translate",
      "name": "Amazon Translate",
      "timing": {
        "provider": 0.121953
      },
     "vendor": "Amazon",
     "description": "Translate",
     "logo": "https://inten.to/img/api/aws.png"
    }
   }
  }
 ],
 "meta": {
   "providers": [
     {
       "id": "ai.text.translate.amazon.translate",
       "name": "Amazon Translate",
       "timing": {
        "provider": 0.121953
       },
       "vendor": "Amazon",
       "description": "Translate",
       "logo": "https://inten.to/img/api/aws.png"
     }
   ],
   "from": "en",
   "to": "es",
   "format": null,
   "glossary": null,
   "smart_routing": "default",
   "category": "default",
   "own_keys": false,
   "size": 37,
   "intento_user_agent": [],
   "userdata": {},
   "user_key_label": "production",
   "is_trace": false
 },
 "error": null
}

In the case of Xliff translation, the result will contain the translated xliff:

{
    "id": "80fab22b-f999-421f-9ac4-c0b7e55a2158",
    "done": true,
    "response": [
     {
        "results": "<TRANSLATED XLIFF>",
...