Engine Suggestions API

Feedback zu Ihren Übersetzungen kommt selten per Klick im Dashboard. Es steckt in einer Zeile in Ihrem Support-Tool, einer Notiz von einem Prüfer oder einem Eintrag in Ihrer QA-Warteschlange – „Produktnamen nicht übersetzen“, „im Deutschen die formelle Anrede verwenden“. Die Engine Suggestions API macht aus diesem Freitext per Code konkrete Änderungen an der Engine: Sie senden das Feedback als Text, die Plattform wertet es aus, und Sie erhalten konkrete, strukturierte Änderungen für das Glossar, die Anweisungen oder die Markenstimme Ihrer Engine zur Übernahme zurück.

Das ist das programmatische Gegenstück zur Dashboard-Funktion. Dort werden Vorschläge automatisch generiert, wenn Ihre KI-Bewerter eine Übersetzung niedrig bewerten; hier liefern Sie das Signal in Form von Text. In beiden Fällen ist das Ergebnis dasselbe – ausstehende Vorschläge, die Sie prüfen und übernehmen.

Der Ablauf besteht aus zwei Teilen. Die Generierung ist asynchron – Sie übergeben Feedback, und die Plattform verarbeitet es im Hintergrund und legt ausstehende Vorschläge auf der Engine ab. Die Prüfung ist synchron – Sie listen die ausstehenden Vorschläge auf, lesen, was jeweils vorgeschlagen wird, und übernehmen oder verwerfen sie einzeln. Diese Seite behandelt beides. Für die Dashboard-Erfahrung – automatische Generierung aus niedrigen Prüfungswerten, den Tab „Suggestions“, Benachrichtigungen – siehe Engine Suggestions.

Aus Feedback generieren#

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

Senden Sie eine Klartextbeschreibung dessen, was die Engine falsch macht. Die Plattform wertet diesen Text zusammen mit der aktuellen Konfiguration der Engine aus und schlägt atomare Änderungen vor – etwas, das in der Engine bereits vorhanden ist, wird nicht erneut vorgeschlagen. Die Generierung läuft asynchron, daher kommt die Antwort sofort zurück, sobald die Aufgabe angenommen wurde, nicht erst dann, wenn die Vorschläge fertig sind.

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 bedeutet, dass die Plattform die Aufgabe angenommen hat – nicht, dass bereits Vorschläge vorliegen. Die Generierung ist ein einzelner Hintergrundschritt: Sie liest Ihren Text, wertet die Konfiguration aus, gleicht gegen bereits Vorhandenes ab und speichert alles, was sie vorschlägt. Es kann völlig legitim sein, dass ein Durchlauf nichts vorschlägt (etwa weil das Feedback zu vage war oder die Engine das bereits abdeckt). Rufen Sie die Ergebnisse ab, indem Sie kurz darauf die Vorschläge der Engine auflisten.

Ausstehende Vorschläge auflisten#

GET /engines/:id/suggestions

Gibt die Vorschläge der Engine zurück – also das Ergebnis jedes Generierungslaufs, egal ob er durch Text, die manuelle Schaltfläche oder automatisch durch niedrige Prüfungswerte ausgelöst wurde. Jeder Eintrag ist eine vorgeschlagene Änderung inklusive Begründung.

[
  {
    "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"
  }
]

Das payload ist das entscheidende Detail, das das Übernehmen so leichtgewichtig macht: Die vorgeschlagene Änderung ist bereits bei der Generierung vollständig strukturiert, daher ist das Übernehmen ein einfacher Schreibvorgang und keine weitere KI-Runde. Sie entscheiden; die Plattform bewertet nicht noch einmal neu.

Einen Vorschlag übernehmen#

POST /engine-suggestions/:id/apply

Schreibt die vorgeschlagene Änderung in die Engine und markiert den Vorschlag als applied. Das ist ein deterministischer Schreibvorgang des payload, das Sie bereits in der Liste gesehen haben – es gibt keinen zweiten KI-Aufruf. Was Sie geprüft haben, ist also genau das, was geschrieben wird. Ein Vorschlag vom Typ add_* erstellt einen neuen Glossareintrag, eine neue Anweisung oder eine neue Markenstimme; ein Vorschlag vom Typ update_* ändert den bestehenden Eintrag, der durch targetId referenziert ist.

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

Die Antwort zeigt den Vorschlag im Status applied, wobei appliedTargetId jetzt auf den tatsächlichen Engine-Eintrag verweist, der erstellt oder aktualisiert wurde. Dieser Eintrag ist ab dann ein ganz normaler Glossareintrag, eine normale Anweisung oder eine normale Markenstimme – Sie können ihn wie jeden anderen öffnen, bearbeiten oder löschen.

Einen Vorschlag verwerfen#

POST /engine-suggestions/:id/dismiss

Verwirft einen Vorschlag, den Sie nicht übernehmen möchten, markiert ihn als dismissed und lässt die Engine unverändert. Verwenden Sie dies, wenn ein Vorschlag für Ihr Produkt nicht passt – die Engine wird nicht geändert, und der Vorschlag erscheint nicht länger als ausstehend.

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.

Der Ablauf, von Anfang bis Ende#

Die vier Endpunkte bilden einen geschlossenen Zyklus, den Sie vollständig aus Ihrem Code steuern können: Feedback einspeisen, nachlesen, was vorgeschlagen wurde, und die Änderungen übernehmen, denen Sie zustimmen.

Nächste Schritte#