Lesen Sie die übersetzte Ausgabe einer einzelnen Sprache und den Verlauf pro Stufe, der zeigt, wie sie entstanden ist.
Zu diesem Endpunkt greifen Sie, sobald Sie eine jobId haben – zurückgegeben im 202 von create, per webhook zugestellt oder unter einer Job-Gruppe aufgeführt. Der Gruppen-Endpunkt zeigt Ihnen, wie viele Sprachen fertig sind. Dieser Endpunkt zeigt Ihnen, was eine einzelne Sprache geliefert hat – und was unterwegs passiert ist.
GET /jobs/localization/:jobIdNeu bei asynchroner Lokalisierung? Starten Sie mit dem Überblick.
Genau darum geht es auf dieser Seite. Die Antwort einer Gruppe ist eine Übersicht – Zähler und Status pro Job, erklärt auf der Seite zur Job-Gruppe. Ein einzelner Job ist der vollständige Datensatz einer Sprache: die übersetzte outputData, der finale status, mögliche warnings und ein steps[]-Verlauf aller Stufen, die die Pipeline durchlaufen hat. Wenn Sie bereit sind, den deutschen Text in Ihre Datenbank zu schreiben, ist das genau der Aufruf, der ihn Ihnen liefert.
Authentifizierung#
Übergeben Sie Ihren API-Schlüssel im Header X-API-Key. Schlüssel gelten organisationsweit und geben Zugriff auf jede Engine in der Organisation. Details finden Sie unter Authentifizierung.
Antwort#
Das Feld outputData spiegelt die Struktur der Eingabe-data: Jeder String-Wert wird übersetzt, jeder Nicht-String-Wert (Zahlen, Boolesche Werte, null) bleibt an derselben Stelle erhalten. Gleiche Schlüssel, gleiche Verschachtelung, gleiche Array-Reihenfolge – nur die Strings ändern sich.
{
"id": "ljb_A1b2C3d4E5f6G7h8",
"groupId": "ljg_A1b2C3d4E5f6G7h8",
"targetLocale": "de",
"status": "completed",
"outputData": {
"id": "course_101",
"title": "Einführung in maschinelles Lernen",
"steps": [
{ "heading": "Was ist ML?", "body": "Maschinelles Lernen ist ein Teilbereich der künstlichen Intelligenz." },
{ "heading": "Überwachtes Lernen", "body": "Trainieren eines Modells mit gelabelten Daten." }
],
"metadata": { "author": "Dr. Smith", "difficulty": "beginner" }
},
"errorMessage": null,
"warnings": [],
"callbackStatus": "delivered",
"createdAt": "2026-03-16T10:30:00.000Z",
"startedAt": "2026-03-16T10:30:01.000Z",
"completedAt": "2026-03-16T10:30:04.000Z",
"steps": [
{
"stepId": "localize",
"type": "action",
"status": "completed",
"errorMessage": null,
"externalRefType": null,
"externalRefId": null,
"externalRefUrl": null,
"createdAt": "2026-03-16T10:30:01.000Z",
"startedAt": "2026-03-16T10:30:01.000Z",
"completedAt": "2026-03-16T10:30:04.000Z"
}
]
}Der Block metadata oben blieb unverändert – Dr. Smith und beginner sind Nicht-String-Blätter, die die Engine unangetastet gelassen hat. Die outputData, die Sie zurückbekommen, hat dieselbe Form wie die, die Sie gesendet haben. So kann derselbe Code, der die Payload aufgebaut hat, auch die Übersetzung verarbeiten.
| Feld | Beschreibung |
|---|---|
id | Die ID dieses Jobs (ljb_…). Der Wert, den Sie im Pfad übergeben haben. |
groupId | Die übergeordnete Job-Gruppe (ljg_…), zu der dieser Job gehört. Übergeben Sie sie an den Job-Gruppen-Endpunkt, um alle parallelen Sprachen auf einmal zu sehen. |
targetLocale | Die BCP-47-Sprache, in die dieser Job übersetzt hat – pro Zielsprache gibt es genau einen Job. Nach diesem Feld verzweigen Sie, um outputData in die richtige Spalte oder Datei zu schreiben. |
status | queued, processing, completed, completed_with_warnings oder failed. |
outputData | Übersetzter Inhalt, der der Eingabestruktur entspricht. Vorhanden, wenn status completed oder completed_with_warnings ist. |
errorMessage | Fehlerbeschreibung. Vorhanden, wenn status failed ist, sonst null. |
warnings | Nicht kritische Ausfälle von Pipeline-Stufen. Jeder Eintrag ist { step, message }. Leer, außer wenn status completed_with_warnings ist. |
callbackStatus | Status der Webhook-Zustellung: pending, delivered oder failed. null, wenn keine Callback-URL konfiguriert ist. |
createdAt | Zeitpunkt, zu dem der Job angenommen wurde (der Zeitstempel des 202, mit dem er erstellt wurde). |
startedAt | Zeitpunkt, zu dem die Engine mit der Übersetzung dieser Sprache begonnen hat. Wird gesetzt, sobald der Job queued verlässt. |
completedAt | Zeitpunkt, zu dem der Job einen finalen Zustand erreicht hat. Wird gesetzt, sobald status completed, completed_with_warnings oder failed ist. |
steps | Ausführungsdatensätze pro Stufe. Enthält immer den Schritt localize sowie einen Eintrag pro aktivierter optionaler Pipeline-Stufe. Die vollständige Struktur finden Sie unter Observe pipeline runs. |
outputData ist null, bis der Job abgeschlossen ist
Solange status queued oder processing ist, ist outputData leer und errorMessage null – es gibt noch nichts zu lesen. Lesen Sie outputData erst, wenn status completed oder completed_with_warnings erreicht hat; bei failed lesen Sie stattdessen errorMessage. Verzweigen Sie zuerst nach status und greifen Sie erst danach auf die Payload zu.
Job-Statuswerte#
Ein Job geht von queued zu processing und dann in genau einen finalen Zustand über. Verzweigen Sie nach status, bevor Sie irgendetwas anderes lesen – dieses Feld sagt Ihnen, welche Felder befüllt sind.
| Status | Bedeutung | Was Sie lesen sollten |
|---|---|---|
queued | Angenommen, aber noch nicht gestartet. | Noch nichts – pollen oder auf den Webhook warten. |
processing | Die Engine übersetzt diese Sprache gerade. | Noch nichts. |
completed | Übersetzung abgeschlossen, alle aktivierten Stufen waren erfolgreich. | outputData. |
completed_with_warnings | Die Übersetzung ist abgeschlossen und outputData vollständig, aber eine nicht kritische Pipeline-Stufe ist fehlgeschlagen. | outputData, dann warnings. |
failed | Der Job hat keine Übersetzung geliefert. | errorMessage. |
completed_with_warnings liefert trotzdem eine Übersetzung
completed_with_warnings ist kein weicher Fehler. Sie erhalten vollständige outputData – der zentrale Übersetzungsschritt war erfolgreich. Geändert hat sich nur, dass eine nicht kritische Stufe (zum Beispiel pre-edit oder back-translation) nicht abgeschlossen wurde und jeder Fehler in warnings als { step, message } protokolliert ist. Behandeln Sie die Ausgabe als nutzbar; behandeln Sie warnings als Qualitätssignal, das den Personen angezeigt werden sollte, die Übersetzungen prüfen. Nur failed bedeutet, dass es keine Übersetzung zum Lesen gibt.
Unbekannte Statuswerte behandeln
Die fünf Statuswerte oben sind heute der Vertrag. Pipeline-Stufen entwickeln sich weiter, behandeln Sie status also als offene Menge: Verzweigen Sie nach den Werten, die Sie kennen, und leiten Sie alles Unerwartete an einen Standardfall weiter, der outputData liest, falls vorhanden, und andernfalls protokolliert. Ein switch ohne Fallback ist genau die Zeile, die an dem Tag bricht, an dem ein neuer Zustand ausgeliefert wird.
Das steps-Array#
steps[] ist der Verlauf pro Stufe hinter einem einzelnen Job – ein Datensatz für jede Stufe, die die Engine der Reihe nach ausgeführt hat. Jeder Job enthält mindestens den Schritt localize, weil die Kernübersetzung immer läuft. Jede optionale Pipeline-Stufe, die Sie aktiviert haben, fügt einen weiteren Datensatz hinzu. Ein Job ohne zusätzliche Stufen zeigt also nur einen einzelnen localize-Schritt; ein Job mit aktiviertem Pre-Edit und Back-Translation zeigt drei.
Genau das macht einen Job nachvollziehbar statt zur Blackbox. Sie müssen nicht darauf vertrauen, dass eine Stufe gelaufen ist – Sie lesen ihren Datensatz: welche Stufe (stepId), ob sie completed, failed oder skipped wurde, was sie gekostet hat (costUsd) und wann sie begonnen und geendet hat. Bei Stufen mit menschlicher Prüfung verweist externalRef* auf den externen Datensatz.
"steps": [
{
"stepId": "preEdit",
"type": "action",
"status": "completed",
"errorMessage": null,
"costUsd": 0.0012,
"createdAt": "2026-03-16T10:30:01.000Z",
"completedAt": "2026-03-16T10:30:02.000Z"
},
{
"stepId": "localize",
"type": "action",
"status": "completed",
"errorMessage": null,
"costUsd": 0.0184,
"createdAt": "2026-03-16T10:30:02.000Z",
"completedAt": "2026-03-16T10:30:05.000Z"
}
]Ein failed-Eintrag hier bedeutet nicht zwangsläufig, dass der Job fehlschlägt. Wenn eine nicht kritische Stufe fehlschlägt, lautet ihr steps[]-Datensatz auf failed, derselbe Fehler erscheint auch im Top-Level-warnings des Jobs, und der Job erreicht trotzdem completed_with_warnings mit vollständiger outputData. Die vollständige Datensatzstruktur – jedes Feld, jede stepId, die Semantik von completed/failed/skipped – steht auf einer zentralen Seite: Observe pipeline runs. Diese Seite zeigt Ihnen, wo Sie sie bei einem Job finden; jene Seite legt sie fest.
Einen abgeschlossenen Job lesen#
Ein typischer Consumer verzweigt nach status, schreibt bei Erfolg outputData und protokolliert bei einem Fehler errorMessage. Der unten stehende Copy-paste-Aufruf gibt die oben gezeigte Payload zurück.
const jobId = "ljb_A1b2C3d4E5f6G7h8";
const response = await fetch(`https://api.lingo.dev/jobs/localization/${jobId}`, {
headers: { "X-API-Key": process.env.LINGO_API_KEY },
});
const job = await response.json();
switch (job.status) {
case "completed":
case "completed_with_warnings":
// outputData is populated; warnings may carry non-critical stage failures
await db.content.update({
where: { id: job.outputData.id },
data: { [`content_${job.targetLocale}`]: job.outputData },
});
if (job.warnings.length) console.warn(job.targetLocale, job.warnings);
break;
case "failed":
console.error(`${job.targetLocale} failed: ${job.errorMessage}`);
break;
default:
// queued or processing - nothing to read yet; also catches future states
break;
}Polling vs. Push
Dieser Endpunkt ist eine Momentaufnahme. Für die meisten Jobs braucht die Engine 2–8 Sekunden pro Sprache, daher ist beim Polling ein Intervall von 2 Sekunden ein sinnvoller Start. Wenn Sie Polling ganz vermeiden möchten, registrieren Sie einen webhook und rufen den Job nur dann ab, wenn er meldet, dass die Sprache fertig ist – oder beobachten die ganze Gruppe über WebSocket. So oder so ist ein finaler GET hier die maßgebliche Ausgabe von outputData.
Wenn dieser Endpunkt einen Fehler zurückgibt – eine unbekannte jobId, ein fehlender Schlüssel –, folgt er dem Standardmodell für JSON-Fehler. Siehe Fehler und Statuscodes.
