Einen Workflow für die Übersetzungs-API aufbauen

Übersetze Anwendungsdatensätze direkt auf dem Server und verknüpfe akzeptierte Sprachversionen zuverlässig mit der Quellrevision, auf die sie sich beziehen.

Wenn jemand in der Redaktion eine Produktbeschreibung aktualisiert, muss jede übersetzte Version diese Änderung übernehmen. Die API-Antwort liefert den neuen Text. Deine Anwendung entscheidet, zu welchem Datensatz er gehört, ob die Quelle noch aktuell ist und ab wann ihn die Leserschaft zu sehen bekommt.

Diese Anleitung baut eine erste Übersetzungsanfrage zu einem wiederholbaren Backend-Workflow aus. Er eignet sich für Datensätze, die deine Anwendung selbst verwaltet, etwa Produktbeschreibungen und Hilfeeinträge. Für statische Anwendungsressourcen passt oft ein CI-Datei-Workflow besser, weil Ressourcenkompilierung und Repository-Prüfung bereits einen Rahmen für die Validierung bieten.

Zusammenhängende Inhalte senden #

Erstelle einen Lokalisierungsauftrag mit einem einzelnen eingebetteten JSON-Dokument für einen Produktdatensatz. Fasse zusammengehörige Felder in Gruppen zusammen, damit der Kontext ihren Zweck beschreiben kann, und behalte stabile Schlüssel bei, damit sich das heruntergeladene Objekt wieder genau diesen Feldern zuordnen lässt.

Sende diesen Anfragetext mit einem API-Schlüssel und einem stabilen Idempotency-Key für diese Revision an POST /v2/organizations/:orgId/localization/jobs:

json
{
  "engineId": "YOUR_ENGINE_ID",
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "documents": [
    {
      "key": "products/bottle.json",
      "format": {
        "type": "json",
        "options": {
          "context": "Product listing for a reusable drinks bottle",
          "hints": {
            "$.title": ["Catalog card title"],
            "$.description": ["Short product description; do not add specifications"]
          }
        }
      },
      "source": {
        "content": {
          "title": "Insulated bottle",
          "description": "Keeps drinks cold during your commute."
        }
      }
    }
  ]
}

Bewahre Zugangsdaten im Backend auf und wähle die Engine ausdrücklich aus. Nutze gemeinsame Glossarvorgaben für die Produktterminologie und Dokumentkontext für den jeweiligen Anwendungsfall. Hinweise und geschützte Pfade findest du in der JSON-Referenz.

Übersetzungen im Hintergrund ausführen #

Speichere die zurückgegebene Auftrags-ID, bevor du den Auftrag startest. Lade alles hoch, was unter uploads aufgeführt ist, und rufe anschließend POST /v2/localization/jobs/:id/start auf. Auch eingebettetes JSON braucht diesen ausdrücklichen Start.

Frage den Auftragsstatus regelmäßig über deinen Backend-Worker ab und lade fertige Zielversionen über die zurückgegebenen URLs herunter. Die Speicheranfrage aus der Redaktion kann bereits beantwortet werden, sobald deine Anwendung diese Arbeit dauerhaft in die Warteschlange aufgenommen hat. Sie muss also nicht offen bleiben, während die Übersetzung oder die menschliche Prüfung läuft.

Bewahre für inkrementelle Aktualisierungen die bisherigen Quellartefakte und die akzeptierten Zielartefakte auf und übergib sie mit der nächsten Dokumentanfrage. Wo die Wiederverwendung an ihre Grenzen stößt, erklärt Dokumentaktualisierungen.

Arbeit nach dem Speichern der Quelle erfassen #

Sobald die Quelltransaktion per Commit abgeschlossen ist, legst du in deinem eigenen Speicher einen Arbeitsdatensatz an – mit Inhalts-ID, Quellrevision, Zielsprache, Datensatz zur Lokalisierungs-Engine bzw. Konfiguration und Verarbeitungsstatus. Stelle die Übersetzung anhand dieses Datensatzes in die Warteschlange. So übersetzt kein Worker eine Änderung, die die Quelltransaktion später wieder zurücknimmt.

Halte für jede Zielsprache ein eigenes Ergebnis fest. Deutsch kann längst fertig sein, während Französisch noch einen erneuten Versuch oder eine Prüfung braucht. Ein einziges pauschales Kennzeichen „übersetzt“ würde diesen Unterschied genau vor der Anwendung verbergen, die entscheidet, was ausgeliefert wird. Alle Statusnamen, die du ergänzt, gehören zum Design deiner Anwendung – nicht zum Antwortvokabular der API.

Ausgaben nur für die vorgesehene Revision akzeptieren #

Quelländerungen und abgeschlossene Übersetzungen können in beliebiger Reihenfolge eintreffen. Ein Beispiel:

EreignisAktion der Anwendung
Revision 12 wird gespeichertRevision 12 für Deutsch in die Warteschlange stellen.
Revision 13 wird gespeichert, bevor diese Arbeit abgeschlossen istRevision 13 in die Warteschlange stellen und als aktuelle Quelle markieren.
Die Übersetzung von Revision 13 ist fertigValidieren und unter Revision 13 akzeptieren.
Die Übersetzung von Revision 12 ist erst später fertigDas erfasste Ergebnis behalten, ohne den akzeptierten Text von Revision 13 zu ersetzen.

Vergleiche bei der Aktivierung die Quellrevision des Arbeitsdatensatzes mit der aktuellen Quelle. Binde Vergleich und Schreibvorgang in deinem Speichersystem an diese Revision, damit dazwischen keine weitere Quelländerung unbemerkt durchrutschen kann. Wurde die Arbeit für die aktuelle Revision nicht in die Warteschlange gestellt oder ist sie fehlgeschlagen, plane die aktuelle Revision neu ein, statt ein älteres Ergebnis einfach umzuetikettieren.

Rufe beim Lesen die akzeptierte Übersetzung für die angeforderte Sprache und Revision ab. Lege fest, was die Anwendung tut, wenn keine vorhanden ist: den Quelltext anzeigen, auf eine festgelegte Ersatzsprache zurückgreifen, eine ausdrücklich nachverfolgte ältere Übersetzung ausliefern oder die Veröffentlichung zurückhalten. Was die richtige Wahl ist, hängt davon ab, was veralteter oder unübersetzter Text für die Leserschaft bedeuten könnte. Eine geänderte Checkout-Bedingung verlangt womöglich strengere Regeln als eine locker formulierte Produktbeschreibung.

Mit Remote-Kennung und lokalem Datensatz wiederherstellen #

Speichere den Idempotenzschlüssel der Anfrage dauerhaft, bevor du sie sendest, und ihre Auftrags-ID, sobald die Erstellung eine Antwort liefert. Wiederhole nach einer Netzwerk-Zeitüberschreitung die unveränderte Erstellungsanfrage mit diesem Schlüssel oder rufe den erfassten Auftrag ab. Ein erneuter Start wirkt sich auf denselben Auftrag aus.

Frage nach vorübergehenden Lesefehlern mit schrittweise längeren Wartezeiten erneut ab. Eine clientseitige Zeitgrenze beendet nur das Warten, nicht die Arbeit auf dem Server. Bewahre fertige Zielausgaben und Details zu fehlgeschlagenen Zielversionen getrennt auf – auch ein fehlgeschlagener Auftrag kann verwendbare fertige Dateien enthalten.

Authentifizierungsfehler, deaktivierte Engines, ungültige Eingaben und Kontolimits musst du beheben. Ein ausstehender Auftrag lässt sich erneut starten, sobald die Zulassungsbeschränkung aufgehoben ist. Ist Arbeit während der Ausführung fehlgeschlagen, behebe die Ursache und sende die betroffenen Dokumente/Sprachen mit einem neuen Idempotenzschlüssel.

Wende bei der Annahme auf jedes Ergebnis dieselbe Revisionskontrolle an – auch auf Ergebnisse, die nach einer Wiederherstellung abgerufen wurden. Ein abgeschlossener Download zeigt nur, dass der Text verfügbar ist. Ob er veröffentlicht werden darf, entscheiden deine Vorgaben für Validierung und Prüfung.

Den Lebenszyklus des Datensatzes testen #

Nimm einen kurzen Datensatz mit einer Variablen und spiele dann eine Quellaktualisierung, eine fehlgeschlagene Sprache und Abschlüsse in vertauschter Reihenfolge durch. Sieh dir neben dem Text auch die gespeicherten Feldschlüssel und Sprachkennungen an. Die Anwendung sollte nur die Version ausliefern, die deine Vorgaben akzeptieren, und Bewerter sollten sie bis zu ihrer Quelle zurückverfolgen können.

Bewahre für die Qualitätsmessung Quelle und Ziel als Paar zusammen mit dem Kriterium auf, anhand dessen sie untersucht wurden. Die Messkonzeption gilt unabhängig vom Generierungs-Workflow. So kann dein Datensatz zurückgegebenen Text, eine Messantwort, die menschliche Annahme und die Veröffentlichung klar auseinanderhalten, statt alles als ein einziges Ereignis zu behandeln.