API Engine Suggestions

Les retours sur vos traductions arrivent rarement sous la forme d’un clic dans un tableau de bord. C’est plutôt une ligne dans votre outil de support, une note d’un relecteur, une entrée dans votre file d’attente QA – « ne traduisez plus le nom du produit », « utilisez le registre formel en allemand ». L’API Engine Suggestions transforme ce texte libre en modifications du moteur depuis le code : vous envoyez le retour sous forme de texte, la plateforme l’analyse, puis vous renvoie des modifications concrètes et structurées du glossaire, des instructions ou de la voix de marque de votre moteur, prêtes à être appliquées.

C’est le pendant programmatique de la fonctionnalité du tableau de bord. Là-bas, les suggestions sont générées automatiquement lorsque vos évaluateur IA attribuent une mauvaise note à une traduction ; ici, c’est vous qui fournissez le signal sous forme de texte. Dans les deux cas, le résultat est le même : des suggestions en attente que vous relisez puis appliquez.

Le flux se découpe en deux temps. La génération est asynchrone : vous transmettez un retour, et la plateforme l’analyse en arrière-plan pour déposer des suggestions en attente sur le moteur. La relecture est synchrone : vous listez les suggestions en attente, lisez ce que chacune propose, puis vous les appliquez ou les ignorez une à une. Cette page couvre les deux. Pour l’expérience dans le tableau de bord – génération automatique à partir de faibles scores de relecture, onglet Suggestions, notifications – consultez Engine Suggestions.

Générer à partir d’un retour#

POST /engines/:id/suggestions/from-text

Envoyez une description en texte brut de ce que le moteur fait mal. La plateforme analyse ce texte ainsi que la configuration actuelle du moteur, puis propose des modifications atomiques – sans reproposer ce que le moteur possède déjà. La génération s’exécute de façon asynchrone ; l’appel renvoie donc dès que le traitement est accepté, et non lorsque les suggestions sont prêtes.

const response = await fetch(
  `https://api.lingo.dev/engines/${engineId}/suggestions/from-text`,
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.LINGO_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      text: "Our German (de-DE) translations keep using the informal 'du'. For our B2B audience they must always use the formal 'Sie'.",
    }),
  },
);

const { enqueued } = await response.json();
console.log(enqueued); // true – generation accepted, running in the background

{ "enqueued": true }

enqueued: true signifie que la plateforme a accepté le traitement, pas que des suggestions existent déjà. La génération est une étape en arrière-plan : elle lit votre texte, analyse la configuration, supprime les doublons avec ce qui existe déjà et enregistre tout ce qu’elle propose. Une exécution peut légitimement ne rien proposer (si le retour est vague, ou si le moteur couvre déjà le point). Consultez les résultats en listant les suggestions du moteur quelques instants plus tard.

Lister les suggestions en attente#

GET /engines/:id/suggestions

Renvoie les suggestions du moteur – le résultat de toute exécution de génération, qu’elle soit déclenchée à partir de texte, via le bouton manuel ou automatiquement à partir de faibles scores de relecture. Chaque entrée correspond à une modification proposée, accompagnée de son raisonnement.

[
  {
    "id": "egs_A1b2C3d4E5f6G7h8",
    "ownerOrganizationId": "org_X1y2Z3a4B5c6D7e8",
    "ownerEngineId": "eng_X1y2Z3a4B5c6D7e8",
    "actionType": "add_instruction",
    "targetKind": "instruction",
    "targetId": null,
    "targetLocale": "de-DE",
    "payload": { "instruction": "Use the formal 'Sie' form in all German translations; never use the informal 'du'." },
    "reasoning": "Feedback states the B2B audience requires formal address, but the engine has no instruction enforcing it.",
    "sourceReviewLogIds": [],
    "status": "pending",
    "appliedTargetId": null,
    "createdAt": "2026-06-18T10:30:00.000Z"
  }
]

Le payload est le détail qui rend l’application peu coûteuse : la modification proposée est entièrement structurée au moment de la génération, donc l’application se résume à une simple écriture, pas à un nouveau cycle d’IA. C’est vous qui décidez ; la plateforme ne refait pas l’analyse.

Appliquer une suggestion#

POST /engine-suggestions/:id/apply

Écrit la modification proposée dans le moteur et marque la suggestion comme applied. Il s’agit d’une écriture déterministe du payload que vous avez déjà vu dans la liste – il n’y a pas de second appel à l’IA, donc ce que vous avez relu est exactement ce qui sera écrit. Une suggestion add_* crée un nouvel élément de glossaire, une nouvelle instruction ou une nouvelle voix de marque ; une suggestion update_* modifie l’entrée existante désignée par targetId.

const response = await fetch(
  `https://api.lingo.dev/engine-suggestions/${suggestionId}/apply`,
  {
    method: "POST",
    headers: { "X-API-Key": process.env.LINGO_API_KEY },
  },
);

const applied = await response.json();
console.log(applied.status);          // "applied"
console.log(applied.appliedTargetId); // "ins_…" – the instruction it just created

La réponse correspond à la suggestion dans son état applied, avec appliedTargetId qui pointe désormais vers la véritable entrée du moteur qu’elle a créée ou mise à jour. À partir de là, cette entrée devient un élément de glossaire, une instruction ou une voix de marque comme les autres – vous pouvez l’ouvrir, la modifier ou la supprimer comme n’importe quelle autre.

Ignorer une suggestion#

POST /engine-suggestions/:id/dismiss

Supprime une suggestion dont vous ne voulez pas, la marque comme dismissed et laisse le moteur intact. Utilisez cette action lorsqu’une proposition ne convient pas à votre produit – le moteur n’est pas modifié, et la suggestion cesse d’apparaître comme en attente.

await fetch(
  `https://api.lingo.dev/engine-suggestions/${suggestionId}/dismiss`,
  {
    method: "POST",
    headers: { "X-API-Key": process.env.LINGO_API_KEY },
  },
);
// The suggestion is now "dismissed"; nothing was written to the engine.

La boucle de bout en bout#

Les quatre endpoints forment un cycle complet que vous pouvez piloter entièrement depuis le code : injectez un retour, consultez ce qui a été proposé, puis validez les modifications avec lesquelles vous êtes d’accord.

Étapes suivantes#