API pro návrhy engine

Zpětná vazba k vašim překladům málokdy přijde jako kliknutí v dashboardu. Spíš je to řádek ve vašem 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“. API pro návrhy engine 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í vám konkrétní, strukturované úpravy glosáře, instrukcí nebo hlasu značky vašeho engine, které pak můžete aplikovat.

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 instruction 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ý už jste viděli ve výpisu – neprobíhá žádné druhé volání AI, takže to, co jste zkontrolovali, je přesně to, co se zapíše. Návrh add_* vytvoří novou položku glosáře, instrukci nebo hlas značky; návrh update_* změní existující položku určenou pomocí 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

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 tato položka běžnou položkou glosáře, instrukcí nebo hlasu značky – můžete ji otevřít, upravit nebo smazat 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#