Localize

Vous avez une chaîne, ou un petit objet de chaînes, qui doit être disponible immédiatement dans une autre langue — un libellé de formulaire, une notification, un court texte d’interface qu’un utilisateur attend. Vous n’avez pas envie de mettre en place un endpoint webhook ni d’interroger un job pour un simple aller-retour. Vous voulez envoyer le texte et récupérer la traduction dans la foulée.

C’est exactement à cela que sert l’endpoint Localize synchrone : une requête, des données traduites renvoyées dans la même structure. Vous envoyez un contenu clé-valeur en POST avec une langue source et une langue cible, l’appel reste bloquant pendant que votre moteur traduit, puis la réponse renvoie le même objet avec ses valeurs traduites et sa structure intacte. Aucun job à suivre, aucun second appel à faire.

La traduction ne repose pas sur un simple appel générique à un modèle. Elle passe par le moteur de localisation que vous avez configuré — son glossaire, sa voix de marque, ses instructions et sa sélection de modèle par langue — le même moteur que l’API asynchrone utilise. La seule différence, c’est le format : l’asynchrone déploie une requête sur plusieurs langues et livre les résultats à mesure qu’ils arrivent ; cet appel ne traite qu’une seule paire de langues et renvoie le résultat directement dans la réponse.

Sur cette page

• Requête
• Réponse
• Exemples
• Ce qui se passe pendant la localisation
• Étapes suivantes

Requête#

POST /process/localize

Authentifiez-vous avec l’en-tête X-API-Key. Les clés sont limitées au niveau de l’organisation et donnent accès à tous les moteurs de votre organisation — voir Authentication pour savoir où en générer une, et Errors and status codes pour le modèle d’erreur complet.

{
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocale": "de",
  "data": {
    "greeting": "Hello, world!",
    "cta": "Get started"
  },
  "hints": {
    "cta": ["Landing page", "Primary button"]
  }
}

Réponse#

La réponse contient le contenu traduit dans la même structure que celle que vous avez envoyée, ainsi que le modèle qui l’a produit et le coût de la requête. Les mêmes clés reviennent, avec la même imbrication — votre code peut récupérer la traduction dans une structure qu’il connaît déjà.

L’objet usage détaille le coût de l’appel, afin que vous puissiez attribuer la dépense sans devoir consulter la facturation séparément :

{
  "sourceLocale": "en",
  "targetLocale": "de",
  "data": {
    "greeting": "Hallo, Welt!",
    "cta": "Jetzt starten"
  },
  "model": "anthropic/claude-sonnet-4.5",
  "usage": {
    "inputTokens": 2789,
    "outputTokens": 861,
    "cacheReadTokens": 0,
    "cacheWriteTokens": 0,
    "llmCost": 0.02129,
    "localizationCost": 0.001722,
    "cost": 0.023012
  }
}

Exemples#

Le même appel en cinq langues. Chacun envoie un objet plat pour plus de clarté ; data accepte aussi les objets imbriqués et les tableaux, et la réponse revient dans la structure exacte que vous envoyez.

const response = await fetch(
  "https://api.lingo.dev/process/localize",
  {
    method: "POST",
    headers: {
      "X-API-Key": "your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      engineId: "eng_abc123",
      sourceLocale: "en",
      targetLocale: "de",
      data: {
        greeting: "Hello, world!",
        cta: "Get started",
      },
    }),
  }
);

const { data } = await response.json();
// { greeting: "Hallo, Welt!", cta: "Jetzt starten" }

Ce qui se passe pendant la localisation#

Un seul POST masque une suite d’étapes, et il vaut la peine de les connaître — car c’est elles qui garantissent une sortie cohérente avec le reste de votre contenu localisé, plutôt qu’une proposition isolée d’un modèle. Lorsqu’une requête atteint l’endpoint, le moteur applique toute sa configuration dans l’ordre :

1. Sélection de modèle — Sélectionne le modèle LLM le plus prioritaire correspondant à la paire de langues. Les modèles spécifiques à une langue priment sur les modèles joker (*). Si le modèle principal échoue, le moteur bascule automatiquement vers le modèle suivant dans le classement.

2. Voix de marque — Charge la voix de marque pour la langue cible, avec repli sur la voix de marque joker si aucune version spécifique à cette langue n’existe.

3. Instructions — Charge chaque instruction correspondant à la langue cible, y compris les instructions joker.

4. Recherche dans le glossaire — Découpe les valeurs d’entrée en segments interrogeables, génère des embeddings et lance une recherche de similarité vectorielle dans le glossaire du moteur. Les termes trouvés imposent des traductions exactes, ou marquent certains termes comme non traduisibles afin qu’ils soient conservés tels quels.

5. Génération — Envoie le prompt composé au modèle sélectionné, puis analyse et valide la réponse JSON.

C’est le même pipeline d’étapes du moteur que l’API asynchrone exécute pour chaque job. Choisir le synchrone plutôt que l’asynchrone change le mode de livraison, pas la manière dont la traduction est produite — ainsi, une chaîne traduite ici et la même chaîne traduite dans un job asynchrone s’appuient sur les mêmes termes du glossaire et la même voix.

Étapes suivantes#