# General Translation Platform: Traduire à l’exécution
URL: https://generaltranslation.com/fr/docs/platform/openapi/reference/translation/translate-runtime.mdx
---

title: Traduire à l’exécution
description: Traduisez des chaînes ou du contenu structuré directement depuis une application ou un service avec General Translation. Référence de l’API pour la traduction de contenu à l’exécution.

method: POST
---

Traduit par lots des requêtes associées à des clés vers un seul paramètre régional cible et renvoie les traductions dans la réponse. General Translation privilégie le cache afin que les requêtes répétées soient rapides et peu coûteuses.

## Aperçu [#overview]

```http
POST https://runtime2.gtx.dev/v2/translate
```

**Autorisation** `project:translations:generate` · **Limite de requêtes** Par défaut (200/min)

Traduisez du contenu à la demande depuis votre propre application ou service. Cet endpoint utilise l’URL de base du runtime `https://runtime2.gtx.dev`. Pour traduire des fichiers entiers en arrière-plan à la place, utilisez [Mettre les traductions en file d’attente](/docs/platform/openapi/reference/translation/queue).

## Fonctionnement [#how-it-works]

* Les requêtes associent vos propres clés au contenu source. Chaque requête est traitée indépendamment, et les résultats sont renvoyés avec les mêmes clés.
* Le service vérifie d’abord son cache mémoïsé, puis les traductions en cours, et effectue enfin les traductions restantes avant de renvoyer la réponse. Les nouvelles traductions sont ensuite réécrites dans le cache.
* Le `dataFormat` de chaque requête détermine comment son `source` est analysé : `STRING` (par défaut), `JSX`, `ICU` ou `I18NEXT`.
* Définir `metadata.modelProvider` nécessite un plan Enterprise ; sinon, la requête renvoie `403`.
* Les paramètres régionaux cibles doivent faire partie des paramètres régionaux autorisés du projet.
* Une réponse réussie renvoie `201` (ou `200` si toutes les requêtes ont été servies depuis le cache).

## Requête [#request]

### En-têtes

| En-tête           | Description                                                               | Obligatoire |
| ----------------- | ------------------------------------------------------------------------- | ----------- |
| `x-gt-api-key`    | Clé API du projet ou de l’Organization.                                   | Oui         |
| `x-gt-project-id` | ID du projet. Obligatoire lors de l’utilisation d’une clé d’Organization. | Non         |

### Corps

**Type de contenu** `application/json`

| Champ                   | Description                                                                                      | Type     | Facultatif | Valeur par défaut |
| ----------------------- | ------------------------------------------------------------------------------------------------ | -------- | ---------- | ----------------- |
| [`requests`](#requests) | Association entre une clé de requête et le contenu à traduire ; au moins une entrée est requise. | `object` | Non        | —                 |
| `targetLocale`          | Paramètre régional dans lequel traduire ; ne peut pas être vide.                                 | `string` | Non        | —                 |
| `sourceLocale`          | Paramètre régional du contenu source ; ne peut pas être vide.                                    | `string` | Non        | —                 |
| `metadata`              | Métadonnées partagées par toutes les requêtes.                                                   | `object` | Oui        | —                 |

L’objet `metadata` partagé accepte `modelProvider` (un identifiant autorisé de fournisseur de modèle ; Enterprise uniquement).

#### `requests` [#requests]

**Type** `object` · **Obligatoire**

Chaque valeur correspond à une requête de traduction distincte :

| Field      | Description                                                              | Type      | Optional | Default         |
| ---------- | ------------------------------------------------------------------------ | --------- | -------- | --------------- |
| `source`   | Contenu source à traduire. La structure dépend de `metadata.dataFormat`. | `unknown` | Non      | —               |
| `metadata` | Métadonnées propres à chaque requête.                                    | `object`  | Oui      | Voir ci-dessous |

Champs de `metadata` propres à chaque requête :

| Field        | Description                                                                   | Type     | Optional | Default  |
| ------------ | ----------------------------------------------------------------------------- | -------- | -------- | -------- |
| `dataFormat` | Format du contenu : `STRING`, `JSX`, `ICU` ou `I18NEXT`.                      | `string` | Oui      | `STRING` |
| `context`    | Contexte supplémentaire pour orienter la traduction.                          | `string` | Oui      | —        |
| `id`         | Identifiant de l'entrée fourni par l'appelant.                        | `string` | Oui      | —        |
| `hash`       | Hachage du contenu ; calculé côté serveur s'il est omis.                  | `string` | Oui      | —        |
| `maxChars`   | Longueur maximale, en caractères, de la traduction.                           | `number` | Oui      | —        |
| `actionType` | Type d'action de traduction.                                              | `string` | Oui      | `fast`   |
| `sourceCode` | Extraits du code source environnant pour apporter un contexte supplémentaire. | `object` | Oui      | —        |

## Réponse [#response]

**État** `201 Created`

Chaque entrée est associée à sa clé de requête. Les entrées réussies contiennent la traduction ; celles en échec contiennent une erreur et un code.

```json title="Response"
{
  "key1": {
    "success": true,
    "translation": "Hola, mundo",
    "dataFormat": "STRING",
    "locale": "es"
  }
}
```

## Erreurs [#errors]

| État  | Cause                                                                                                                          |
| ----- | ------------------------------------------------------------------------------------------------------------------------------ |
| `400` | Corps de la requête invalide, ou paramètre régional source/cible invalide.                                                     |
| `401` | Clé API manquante ou invalide.                                                                                                 |
| `402` | Quota de jetons épuisé, ou la requête ne peut pas être facturée.                                                               |
| `403` | La clé API ne dispose pas de `project:translations:generate`, ou un `modelProvider` personnalisé nécessite un plan Enterprise. |
| `429` | Limite de débit dépassée.                                                                                                      |

## Exemple [#example]

```bash
curl -X POST https://runtime2.gtx.dev/v2/translate \
  -H "x-gt-api-key: gtx-api-..." \
  -H "Content-Type: application/json" \
  -d '{
    "requests": {
      "key1": { "source": "Hello, world" }
    },
    "sourceLocale": "en",
    "targetLocale": "es"
  }'
```