API pro návrhy engine

Zpětná vazba k vašim překladům se jen málokdy objeví jako kliknutí v dashboardu. Častěji je to řádek ve vašem interním nástroji podpory, poznámka od hodnotitele nebo položka ve vaší QA frontě – „nepřekládejte název produktu“, „v němčině používejte formální styl“. Engine Suggestions API převádí takový volný text na změny engine přímo z kódu: pošlete zpětnou vazbu jako text, platforma ji vyhodnotí a vrátí konkrétní, strukturované úpravy glosáře, pravidel nebo hlasu značky vašeho engine, které pak můžete použít.

Jde o programovou obdobu funkce v dashboardu. Tam se návrhy generují automaticky, když vaši AI hodnotitelé udělí překladu nízké skóre; tady dodáváte signál jako text vy. V obou případech je výstup stejný – čekající návrhy, které zkontrolujete a aplikujete.

Celý proces má dvě části. Generování je asynchronní – předáte zpětnou vazbu a platforma ji na pozadí vyhodnotí, takže u engine přibudou čekající návrhy. Kontrola je synchronní – vypíšete si čekající návrhy, přečtete si, co který navrhuje, a každý z nich aplikujete nebo zamítnete. Tato stránka pokrývá obojí. Pokud vás zajímá práce v dashboardu – automatické generování z nízkých skóre kontroly, karta Suggestions, notifikace – podívejte se na Návrhy engine.

Generování ze zpětné vazby#

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

Pošlete prostý textový popis toho, co engine dělá špatně. Platforma vyhodnotí tento text spolu s aktuální konfigurací engine a navrhne atomické úpravy – znovu nenavrhne něco, co už engine obsahuje. Generování probíhá asynchronně, takže volání se vrátí hned po přijetí úlohy, ne až ve chvíli, kdy jsou návrhy připravené.

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 znamená, že platforma úlohu přijala, ne že už návrhy existují. Generování probíhá v jednom kroku na pozadí – načte váš text, vyhodnotí konfiguraci, odstraní duplicity vůči tomu, co už v engine je, a uloží vše, co navrhne. Je zcela legitimní, že běh nenavrhne nic (zpětná vazba byla vágní nebo to engine už pokrývá). Výsledky si o chvíli později přečtete pomocí výpisu návrhů engine.

Výpis čekajících návrhů#

GET /engines/:id/suggestions

Vrací návrhy engine – výsledek jakéhokoli běhu generování, ať už spuštěného z textu, ručním tlačítkem nebo automaticky z nízkých skóre kontroly. Každá položka je navržená úprava s připojeným zdůvodněním.

[
  {
    "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 rule enforcing it.",
    "sourceReviewLogIds": [],
    "status": "pending",
    "appliedTargetId": null,
    "createdAt": "2026-06-18T10:30:00.000Z"
  }
]

Právě payload dělá aplikaci nenáročnou: navržená změna je už při generování plně strukturovaná, takže její aplikace je prostý zápis, ne další kolo AI. Rozhodujete vy; platforma znovu neuvažuje.

Aplikace návrhu#

POST /engine-suggestions/:id/apply

Zapíše navrženou změnu do engine a označí návrh jako applied. Jde o deterministický zápis payload, který jste už viděli v seznamu – neprobíhá žádné druhé AI volání, takže se zapíše přesně to, co jste zkontrolovali. Návrh add_* vytvoří novou položku glosáře, pravidlo nebo hlas značky; návrh update_* upraví existující položku určenou v 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 rule it just created

Odpovědí je návrh ve stavu applied, přičemž appliedTargetId teď odkazuje na skutečnou položku engine, kterou vytvořil nebo aktualizoval. Od této chvíle je z ní běžná položka glosáře, pravidlo nebo hlas značky – můžete ji otevřít, upravit nebo smazat stejně jako jakoukoli jinou.

Zamítnutí návrhu#

POST /engine-suggestions/:id/dismiss

Zahodí návrh, který nechcete, označí ho jako dismissed a ponechá engine beze změny. Použijte to ve chvíli, kdy návrh pro váš produkt nedává smysl – engine se nezmění a návrh se přestane zobrazovat jako čekající.

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.

Celý proces od začátku do konce#

Tyto čtyři endpointy tvoří jeden cyklus, který můžete kompletně řídit z kódu: dodat zpětnou vazbu, přečíst si, co bylo navrženo, a potvrdit úpravy, se kterými souhlasíte.

Další kroky#