Ihre Inhalte ändern sich – und jetzt müssen sie jede Sprache erreichen, in der Sie ausliefern. Ein Schulungsmodul bekommt eine neue Lektion. Ein CMS-Eintrag wird gespeichert. Eine Produktbeschreibung wird überarbeitet. Die Übersetzung soll auf Deutsch, Französisch, Japanisch und ein Dutzend weitere Sprachen verteilt werden – und Ihre App soll dabei nicht blockieren.
Die asynchrone Lokalisierungs-API ist genau für diesen Moment gebaut: eine Anfrage, jede Sprache, Ergebnisse, sobald sie eintreffen. Sie senden Ihre Inhalte mit den Zielsprachen einmal per POST, erhalten sofort eine 202 zurück, und die Plattform übersetzt jede Sprache als unabhängigen Hintergrunds-Job. Sie behalten Ihr Glossar, Ihre Markenstimme und Ihre Modellkonfiguration – dieselbe Engine, die auch die synchrone API verwendet – und müssen sich nicht länger selbst um Retries kümmern.
Auf dieser Seite
Das Problem#
Schulungsplattformen, Content-Management-Systeme und E-Learning-Tools müssen Inhalte oft in Dutzende von Sprachen übersetzen, sobald sie erstellt oder aktualisiert werden. Die synchrone Lokalisierungs-API funktioniert, erzwingt im großen Maßstab aber einen Kompromiss.
Nehmen wir ein auf Englisch erstelltes Schulungsmodul, das Lernende in 14 Sprachen erreichen soll. Mit der synchronen API haben Sie zwei Möglichkeiten – und beide haben ihren Preis:
14 parallele Aufrufe abfeuern – eine Anfrage pro Zielsprache, jeweils mit derselben Quelldatenlast. Sie können jede Sprache anzeigen, sobald sie zurückkommt, aber Sie verwalten 14 Netzwerk-Roundtrips mit redundanten Daten und sind selbst für die Retry-Logik verantwortlich, wenn einer davon fehlschlägt.
Alle 14 in einem synchronen Aufruf übersetzen – weniger Roundtrips, aber jetzt warten Sie auf die langsamste Sprache, bevor Sie auch nur eine davon anzeigen können.
So oder so ist Ihre Anwendung beschäftigt, während die Übersetzungen verarbeitet werden. Wenn Ihr Server währenddessen neu startet, sind die laufenden Übersetzungen verloren. Wenn eine Sprache fehlschlägt, liegt die Behandlung partieller Fehler bei Ihnen. Und keiner der beiden Wege gibt Ihren Nutzern ein klares Signal, dass Übersetzungen gerade laufen.
Die asynchrone API hebt diesen Kompromiss auf. Eine Anfrage erstellt eine Jobgruppe mit einem Job pro Zielsprache. Jeder Job läuft unabhängig durch Ihre Lokalisierungs-Engine als dauerhafter Hintergrund-Workflow – ein Serverneustart auf Ihrer Seite kostet Sie also nichts, weil die Arbeit nicht in Ihrem Prozess läuft. Die Ergebnisse werden pro Sprache ausgeliefert, sobald die jeweilige Übersetzung fertig ist. Ihre App bleibt reaktionsfähig. Fehler bleiben isoliert. Die Plattform übernimmt Retries und Auslieferung.
Eine Sprache, und Sie können eine Sekunde warten? Dann nutzen Sie Sync.
Die asynchrone API spielt ihre Stärken aus, wenn Sie viele Sprachen, lange Inhalte oder eine UI haben, die Fortschritt anzeigen soll. Wenn Sie nur ein einzelnes Sprachpaar brauchen und auf einen Roundtrip warten können, ist der synchrone Localize-Endpunkt der einfachere Aufruf – eine Anfrage, übersetzte Daten direkt in der Antwort, kein Webhook-Endpunkt erforderlich. Nutzen Sie Async, wenn der Job zu groß, zu langsam oder zu sprachintensiv ist, um darauf zu blockieren.
So funktioniert's#
Drei Schritte – und nur der erste findet in Ihrem Anfrage-/Antwortzyklus statt. Die anderen beiden laufen auf der Plattform, in ihrem eigenen Tempo.
Eine Anfrage senden
Senden Sie Ihre Inhalte und Zielsprachen per POST an /jobs/localization. Die API validiert die Nutzlast, erstellt eine Jobgruppe mit einem Job pro Sprache und gibt 202 mit der Gruppen-ID und einer Job-Zusammenfassung zurück. Ihre Anwendung kann sofort weitermachen – innerhalb dieses Aufrufs wird nichts übersetzt. Unter Jobs erstellen finden Sie die vollständige Struktur von Anfrage und Antwort.
Die Plattform verarbeitet jede Sprache unabhängig
Jeder Job läuft über Ihre Lokalisierungs-Engine in einem dauerhaften Hintergrund-Workflow und verwendet dieselbe Modellauswahl, dasselbe Glossar, dieselbe Markenstimme und dieselben Anweisungen wie die synchrone API. Jeder Job kann optional eine Pipeline mit den Stufen Pre-Edit, menschliche Prüfung, Post-Edit, Umformulierung und Rückübersetzung durchlaufen. Ein Job wechselt von queued zu processing und dann in einen Endzustand: completed, completed_with_warnings oder failed – und das Ergebnis einer Sprache blockiert niemals eine andere.
Ergebnisse empfangen, sobald sie eintreffen
Sobald eine Sprache fertig ist, liefert die Plattform ihr Ergebnis an Ihre Webhook-URL. Für Live-Fortschritt in Ihrer UI – ein Zähler wie „3 von 14 bereit“, der sich aktualisiert, wenn Jobs abgeschlossen werden – verbinden Sie sich mit dem WebSocket der Gruppe. Wenn Sie lieber pollen möchten, können Sie die Gruppe in Intervallen abfragen.
Authentifizierung
Jede Anfrage – REST und WebSocket – authentifiziert sich mit Ihrem X-API-Key-Header. Schlüssel gelten organisationsweit und erreichen jede Engine in der Organisation. Details finden Sie unter Authentifizierung; unter API-Schlüssel erfahren Sie, wie Sie einen erstellen.
Das Jobgruppen-Modell#
Eine Übermittlung erzeugt eine Gruppe, die einen Job pro Zielsprache enthält. Dieses Modell ist der ganze mentale Rahmen – und genau das macht die schwierigen Fragen beantwortbar.
Wer skeptisch mitliest, geht die Liste wahrscheinlich schon durch: Was passiert, wenn eine Sprache fehlschlägt? Und was passiert mit meiner App, während all das läuft? Das Gruppenmodell beantwortet beides.
- Fehler bleiben isoliert, weil jede Sprache ihr eigener Job ist. Wenn Deutsch erfolgreich ist und Japanisch fehlschlägt, wird die deutsche Übersetzung ganz normal ausgeliefert und der japanische Job trägt sein eigenes
errorMessage. Die Gruppe meldetpartial, und die erfolgreich abgeschlossene Arbeit wird trotzdem ausgeliefert. Ein Fehler in einer Sprache kann keine andere zurückrollen, die bereits abgeschlossen ist. Die vollständige Statussemantik finden Sie unter Eine Jobgruppe verfolgen. - Laufende Arbeit übersteht einen Neustart, weil sie nicht in Ihrem Prozess läuft. Jeder Job ist ein dauerhafter Hintergrund-Workflow auf der Plattform. Wenn Ihr Server neu startet, geht nichts verloren, was gerade läuft – Sie verbinden sich erneut oder pollen, und die Gruppe ist genau dort, wo Sie sie verlassen haben.
- Die Gruppe ist ein Fortschrittsmodell, das Sie an eine UI anbinden können. Speichern Sie die
groupIdaus der202und steuern Sie dann eine Fortschrittsanzeige über Webhook-Auslieferungen oder WebSocket-Snapshots. „3 von 14 Sprachen bereit“ ist ein Zähler über die untergeordneten Jobs der Gruppe.
Die ehrliche Kehrseite dieses Modells: Sie übernehmen ein kleines bisschen Integrationsaufwand, den der synchrone Aufruf nicht verlangt. Um Ergebnisse zu empfangen, betreiben Sie einen HTTPS-Webhook-Endpunkt oder halten eine serverseitige WebSocket-Verbindung offen, und Sie verarbeiten jede Sprache, sobald sie eintrifft, statt übersetzte Daten direkt aus einer einzigen Antwort zu lesen. Im Gegenzug übernimmt die Plattform Retries, Fehlerisolierung und Auslieferung – und Ihre App blockiert nie auf eine Übersetzung.
Genau dafür wurde die asynchrone API gebaut: eine Anfrage, jede Sprache, Ergebnisse, sobald sie eintreffen. Die nächsten Seiten sind die Verben dieses Satzes.
