API für Engine-Vorschläge
Vorschläge aus Feedback generieren, Änderungen ansehen und Vorschläge gezielt anwenden oder verwerfen.
Engine-Vorschläge enthalten Änderungsvorschläge für Glossarbegriffe, Regeln und Markenstimmenvarianten. Führen Sie vor dem Anwenden eine Prüfung des vorgeschlagenen Inhalts und des Ziels durch. Bei der Generierung werden Vorschläge zur Warteschlange hinzugefügt; erst das Anwenden eines Vorschlags ändert die Vorgaben der Engine.
Engine-Vorschläge sind im Enterprise-Tarif verfügbar. Der Aufrufer benötigt außerdem Zugriff auf die Engine und die entsprechenden Berechtigungen für Vorschläge. Den Dashboard-Workflow finden Sie unter Vorschläge in der Warteschlange.
Alle folgenden Routen verwenden https://api.lingo.dev und API-Authentifizierung.
Generierung anfordern #
So generieren Sie Vorschläge aus dem gesammelten Feedback der Engine:
POST /v2/engines/:engineId/engine-suggestions/generate
X-API-Key: YOUR_API_KEYDiese Anfrage hat keinen Body. So übergeben Sie Feedback direkt:
POST /v2/engines/:engineId/engine-suggestions/from-text
Content-Type: application/json
X-API-Key: YOUR_API_KEY{
"text": "In German account settings, use Abonnement for subscription. Avoid Mitgliedschaft for this product feature."
}text darf nicht leer sein oder ausschließlich aus Leerraum bestehen und darf höchstens 10.000 Zeichen enthalten. In diesem Modus entstehen Vorschläge direkt aus dem übergebenen Feedback. Geben Sie daher die gewünschte Korrektur und die Sprache an, für die sie gilt.
Beide Routen geben HTTP 200 mit folgendem Inhalt zurück:
{ "enqueued": true }Dies bestätigt die Aufnahme in die Warteschlange, nicht den Abschluss der Generierung. Rufen Sie nach der Verarbeitung die ausstehenden Vorschläge der Engine ab. Wenn es keine sinnvolle Änderung gibt, kann die Generierung auch ohne Vorschläge enden. Eine unmittelbar danach leere Liste bedeutet nicht, dass die Anfrage fehlgeschlagen ist.
Vorschläge auflisten #
GET /v2/organizations/:orgId/engine-suggestions?engineIds=YOUR_ENGINE_ID&statuses=Pending&limit=25| Abfrageparameter | Bedeutung |
|---|---|
engineIds | Auf ausgewählte Engines beschränken. |
targetLocales | Geltungsbereiche nach Sprache, einschließlich * für sprachübergreifende Vorgaben. |
statuses | Pending, Applied oder Dismissed; Standardwert ist Pending. |
ids | Ausgewählte Vorschläge anhand ihrer IDs abrufen. |
limit | Ganzzahl von 1 bis 100; Standardwert ist 25. |
cursor | Opaker Cursor für die Paginierung. |
Geben Sie Array-Parameter für mehrere Werte wiederholt an. Die Antwort enthält data und meta.nextCursor; fahren Sie mit denselben Filtern fort, bis nextCursor den Wert null hat.
Jeder Vorschlag enthält:
| Feld | Bedeutung |
|---|---|
id, organizationId, engineId | Identität und Eigentümerschaft des Vorschlags. |
targetLocale | Geltungsbereich der vorgeschlagenen Änderung nach Sprache. |
change | Typisierte Änderung, wie unten beschrieben. |
reasoning | Begründung für den Vorschlag. |
sources | Verweise auf Belege, etwa eine Prüfung durch ein Bewertungssystem, eine manuelle Bearbeitung oder ein Arbeitselement. |
status | Objekt, dessen type den Wert Pending, Applied oder Dismissed hat. |
destination | Vorgabensatz, auf den die Änderung angewendet wird, oder null, wenn nicht verfügbar. |
createdAt, updatedAt | ISO-Zeitstempel. |
Ein Ziel enthält kind (Glossary, Ruleset oder BrandVoice), id (kann null sein), name und willCreate. Anhand von willCreate erkennen Sie, ob beim Anwenden ein Vorgabensatz erstellt wird. Der Status nach dem Anwenden enthält at, by (kann null sein) und target (kann null sein); vom System verworfene Vorschläge können ein reason enthalten.
Änderung ansehen #
change.type | Inhalt |
|---|---|
AddGlossaryTerm | sourceLocale, sourceText, targetLocale, targetText, description (kann null sein) und nonTranslatable. |
UpdateGlossaryTerm | termId, glossaryId (kann null sein) und die übergebenen Felder für den Ersatz. |
AddRule | name, text und targetLocale. |
UpdateRule | ruleId und die übergebenen Felder name, text oder targetLocale. |
AddBrandVoiceVariation | targetLocale und text. |
UpdateBrandVoiceVariation | variationId und das übergebene Feld targetLocale oder text. |
Aktualisierungsvorschläge enthalten nur die Felder, die geändert werden. Kontrollieren Sie vor einer weitreichenden Änderung den Zieldatensatz und ob dessen Vorgabensatz auch an anderer Stelle verwendet wird.
Anwenden oder verwerfen #
POST /v2/engine-suggestions/:id/applyPOST /v2/engine-suggestions/:id/dismissBeide Anfragen haben keinen Body und geben den aktualisierten Vorschlag zurück. Eine Entscheidung ist nur für ausstehende Vorschläge möglich. Beim Anwenden werden die vorgeschlagenen Vorgaben gespeichert; beim Verwerfen bleiben die Vorgaben unverändert.
Wenn das Ziel geändert wurde oder nicht mehr existiert, kann das Anwenden EngineSuggestionConflicts oder EngineSuggestionTargetGone zurückgeben. Laden Sie den Vorschlag und sein Ziel neu, bevor Sie eine Korrektur auswählen. Eine erneute Entscheidung über einen bereits entschiedenen Vorschlag gibt EngineSuggestionNotPending zurück. Sehen Sie sich nach einer unklaren Antwort den Status an, statt den Schreibvorgang blind zu wiederholen.
Über mehrere Vorschläge entscheiden #
Senden Sie { "ids": ["FIRST_ID", "SECOND_ID"] } per POST an:
/v2/engine-suggestions/apply-many: 1–25 eindeutige IDs./v2/engine-suggestions/dismiss-many: 1–1.000 eindeutige IDs.
Beim Anwenden werden applied und failed zurückgegeben, beim Verwerfen dismissed und failed. Jeder fehlgeschlagene Eintrag enthält id und ein benanntes error. Auch eine erfolgreiche HTTP-Antwort kann einzelne Fehler enthalten. Erfolgreiche Elemente bleiben erhalten, wenn ein anderes Element fehlschlägt. Behandeln Sie daher jedes Ergebnis unabhängig.
Überarbeitete Vorgaben verwenden #
Sehen Sie sich nach dem Anwenden das Glossar, die Regeln oder die Markenstimme der Engine an und testen Sie repräsentative Inhalte. Wenden Sie akzeptierte Vorgaben an, bevor Sie den neuen Auftrag starten. Um vorhandene Übersetzungen zu aktualisieren, wählen Sie die Inhalte gezielt aus und fordern Sie eine Aktualisierung an; das Anwenden von Vorgaben allein löst keine Anfrage zur erneuten Übersetzung aus.