> For the complete documentation index, see [llms.txt](https://docs.api.intratool.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.api.intratool.de/api-reference/translations.md).

# Translations

## Introduction

The Translations API translates plain text or fields of resources that support the [Translations capability](/introduction/resource-capabilities/translations.md). Each request selects one active target language; source languages are detected automatically.

The examples translate German (`de-DE`) source content into French (`fr-FR`) and Spanish (`es-ES`) so that multiple source fields and target languages are represented.

Set `is_html` for standalone [Rich Text](/introduction/rich-text.md) values so formatting tags are preserved during translation.

## Translate Text

Translate an array of text strings into a target language.

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/translations/translate-text`

**Request Keys**

| Key                | Type       | Default | Description                                                 |
| ------------------ | ---------- | ------- | ----------------------------------------------------------- |
| `target_lang_id`\* | `string`   | -       | Active target [Language](/api-reference/languages.md) key.  |
| `text`\*           | `string[]` | -       | Text strings to translate, up to 50 per request.            |
| `is_html`          | `boolean`  | `false` | Treat every submitted string as HTML and preserve its tags. |

Keys with `*` are required.

**Behavior**

The translator detects the source language for each string. Content considered visually empty, such as empty HTML, is not sent to the provider and is returned unchanged in its original position.

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/translations/translate-text', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'target_lang_id' => 'fr-FR',
        'text' => [
            'Hallo Welt!',
            'Dies ist ein Test.',
            '<p><strong>Fetter Text</strong></p>'
        ],
        'is_html' => true
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "text": [
      "Bonjour le monde !",
      "Ceci est un test.",
      "<p><strong>Texte en gras</strong></p>"
    ]
  }
}
```

## Translate Entities

Translate fields of one or more entities into a target language.

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/translations/translate-entities`

**Request Keys**

| Key                                   | Type       | Default                 | Description                                                |
| ------------------------------------- | ---------- | ----------------------- | ---------------------------------------------------------- |
| `target_lang_id`\*                    | `string`   | -                       | Active target [Language](/api-reference/languages.md) key. |
| `translatables`\*                     | `object[]` | -                       | Resources whose fields should be translated.               |
| `translatables.*.translatable_type`\* | `string`   | -                       | Resource alias, for example `infoboardPost`.               |
| `translatables.*.translatable_id`\*   | `integer`  | -                       | Existing resource ID.                                      |
| `translatables.*.translatable_fields` | `string[]` | All translatable fields | Specific translatable field names.                         |

Keys with `*` are required.

**Behavior**

The endpoint returns existing target-language translations when they are complete and creates missing translations through the configured provider. Unknown, unsupported, inaccessible, and empty resources or fields are skipped.

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/translations/translate-entities', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'target_lang_id' => 'es-ES',
        'translatables' => [
            [
                'translatable_type' => 'infoboardPost',
                'translatable_id' => 410,
                'translatable_fields' => [
                    'title',
                    'text'
                ]
            ]
        ]
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": [
    {
      "id": 601,
      "user_id": 17,
      "lang_id": "es-ES",
      "translatable_type": "infoboardPost",
      "translatable_id": 410,
      "translatable_field": "title",
      "translatable_field_value": "¡Por fin abierto de nuevo!",
      "created_at": "2026-08-06 15:00:00",
      "updated_at": "2026-08-06 15:00:00",
      "deleted_at": null
    },
    {
      "id": 602,
      "user_id": 17,
      "lang_id": "es-ES",
      "translatable_type": "infoboardPost",
      "translatable_id": 410,
      "translatable_field": "text",
      "translatable_field_value": "<p>Por fin han concluido las obras de remodelación de nuestra sucursal: ¡a partir de la semana que viene volveremos a abrir en Limburgo!</p><p></p><p>Como de costumbre, encontrará la rotación actual en su carpeta de archivos.</p>",
      "created_at": "2026-08-06 15:00:00",
      "updated_at": "2026-08-06 15:00:00",
      "deleted_at": null
    }
  ]
}
```