Pipeline-Läufe nachvollziehen

Jede aktivierte Pipeline-Stufe hinterlässt einen Eintrag im Job, damit du nachlesen kannst, was gelaufen ist, statt dich darauf zu verlassen, dass es schon passiert sein wird.

Du hast ein paar Pipeline-Stufen aktiviert – vielleicht Pre-Edit, um den Ausgangstext zu bereinigen, und Back-Translation, um Abweichungen aufzuspüren – und ein Job kam completed_with_warnings zurück. Welche Stufe ist schiefgelaufen? Hat der menschliche Prüfer den Job überhaupt übernommen, oder ist das Zeitfenster abgelaufen? Was haben die zusätzlichen Stufen gekostet? Eine Pipeline, die pro Sprache mehrere KI- und menschliche Schritte ausführt, wird schnell zur Blackbox: Am Ende kommt ein Ergebnis heraus, und du sollst einfach glauben, dass die Stufen dazwischen ihren Job gemacht haben.

Genau das musst du hier nicht. Jede aktivierte Stufe schreibt einen Eintrag in das steps[]-Array des Jobs – welche Stufe, welcher Status, welche Kosten, wann sie gestartet ist und wann sie abgeschlossen wurde. Du liest nach, was jede Stufe gemacht hat; du vertraust nicht einfach darauf, dass sie gelaufen ist. Genau dafür ist diese Seite da.

Auf dieser Seite

• Wo die Einträge liegen
• Das steps-Array
• Wie stepId einer Stufe zugeordnet wird
• Schrittstatus: completed, failed, skipped
• Wie aus einem Schrittfehler eine Job-Warnung wird

Wo die Einträge liegen#

Das steps[]-Array ist ein Feld im Lokalisierungsjob. Du rufst es nicht separat ab – es ist jedes Mal dabei, wenn du den Job ausliest:

GET /jobs/localization/:jobId

Authentifiziere dich mit deinem API-Schlüssel im Header X-API-Key. Der vollständige Endpunkt, die Job-Statuswerte und die Payload outputData werden auf der Seite zum Einzeljob erklärt; hier geht es um ein Feld in dieser Antwort – die Spur pro Stufe – und darum, was sie dir verrät.

Die Regel ist einfach: Jeder Job, den du ausliest, bringt sein eigenes Audit-Log schon mit. Ein Job ohne aktivierte Pipeline zeigt genau einen Eintrag, weil Core Localization immer läuft. Aktivierst du zwei optionale Stufen, bekommst du drei Einträge. Das Array wächst mit der Pipeline: ein Eintrag pro Stufe, in der Reihenfolge, in der die Stufen gelaufen sind.

Das steps-Array#

Jeder Eintrag in steps[] ist der Datensatz einer Stufe. Diese Felder liest du, um einen Lauf zu prüfen – welche Stufe, mit welchem Ergebnis, zu welchen Kosten und wann:

"steps": [
  {
    "stepId": "preEdit",
    "type": "action",
    "status": "completed",
    "errorMessage": null,
    "costUsd": 0.0012,
    "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:02.000Z"
  },
  {
    "stepId": "localize",
    "type": "action",
    "status": "completed",
    "errorMessage": null,
    "costUsd": 0.0184,
    "externalRefType": null,
    "externalRefId": null,
    "externalRefUrl": null,
    "createdAt": "2026-03-16T10:30:02.000Z",
    "startedAt": "2026-03-16T10:30:02.000Z",
    "completedAt": "2026-03-16T10:30:05.000Z"
  }
]

Jeder Eintrag enthält außerdem ein Feld outputData – den Inhalt, den diese Stufe erzeugt hat, in derselben Form wie das outputData des Jobs. Diese Payload ist die Übersetzung, nicht die Audit-Spur, und wird deshalb auf der Seite zum Einzeljob dokumentiert zusammen mit dem outputData auf Job-Ebene; die Felder oben sind die, die du liest, um zu sehen, was die Pipeline getan hat.

Diese Einträge geben dir zwei Dinge, die ein einzelner outputData-Block nicht leisten kann. Erstens: Die Kosten sind pro Stufe aufgeschlüsselt, nicht nur als Summe pro Job – wenn du also Back-Translation aktivierst und die Rechnung steigt, kannst du genau sehen, welche Stufe dafür verantwortlich ist. Zweitens: Das Timing ist pro Stufe sichtbar – ein humanEdit-Eintrag, bei dem startedAt und completedAt Stunden auseinanderliegen, zeigt dir, dass die Wartezeit beim Menschen lag, nicht bei der Engine.

Wie stepId einer Stufe zugeordnet wird#

Jede stepId benennt eine Pipeline-Stufe. Diese Tabelle ordnet den Wert im Eintrag der Stufe zu, für die er steht, inklusive der Seite, auf der dokumentiert ist, was diese Stufe macht:

localize ist die eine stepId, die in jedem Job erscheint, ob mit oder ohne Pipeline – sie ist der Core-Translate-Schritt und läuft immer. Die anderen fünf tauchen nur auf, wenn du diese Stufe auf der Engine oder in der Anfrage aktiviert hast.

Schrittstatus: completed, failed, skipped#

Jeder Schritt hat seinen eigenen status, unabhängig vom Job und von jedem anderen Schritt gesetzt. Es gibt drei Werte:

completed und failed liest du genau so, wie du es erwartest. Bei skipped lohnt sich ein genauerer Blick, denn das ist nicht dasselbe wie „deaktiviert“. Eine Stufe, die du nie aktiviert hast, erzeugt gar keinen Eintrag. Ein skipped-Eintrag bedeutet, dass die Stufe aktiviert war, aber aus einem von der Pipeline definierten Grund übergangen wurde – der klarste Fall ist human review: Wenn das Prüfungsfenster ohne Rückmeldung eines Menschen abläuft, wird diese Stufe als skipped markiert und die KI-Übersetzung als final übernommen. Der Eintrag bleibt trotzdem bestehen, damit das Überspringen sichtbar ist statt stillschweigend zu passieren.

Wie aus einem Schrittfehler eine Job-Warnung wird#

Wenn eine nicht kritische Stufe fehlschlägt, taucht dieser Fehler gleichzeitig an zwei Stellen auf – zwei Ansichten desselben Ereignisses. Im steps[]-Eintrag steht failed mit einem errorMessage – das ist die Detailansicht. Derselbe Fehler erscheint außerdem als Eintrag im übergeordneten warnings-Array des Jobs – das ist die Kurzansicht, nach der dein Status-Handling im Code verzweigt:

{
  "id": "ljb_A1b2C3d4E5f6G7h8",
  "status": "completed_with_warnings",
  "outputData": { "title": "Hallo" },
  "warnings": [
    { "step": "backTranslation", "message": "Back-translation check did not complete" }
  ],
  "steps": [
    { "stepId": "localize", "type": "action", "status": "completed", "errorMessage": null, "costUsd": 0.0184, "completedAt": "2026-03-16T10:30:05.000Z" },
    { "stepId": "backTranslation", "type": "action", "status": "failed", "errorMessage": "Back-translation check did not complete", "costUsd": 0.0031, "completedAt": "2026-03-16T10:30:11.000Z" }
  ]
}

Jeder warnings-Eintrag ist { step, message }, wobei step derselbe stepId ist, den du auch im fehlgeschlagenen Eintrag findest. Die beiden Arrays greifen also ineinander: warnings ist die Kurzliste dessen, was schiefgelaufen ist, und steps[] ist der Ort für die Details dahinter. Lies warnings, um zu entscheiden, ob du die Sprache für eine menschliche Prüfung markieren willst; lies den passenden steps[]-Eintrag, wenn du das errorMessage, die Kosten und das Timing dahinter sehen willst.

Das ist der Mechanismus hinter completed_with_warnings: Die Kernübersetzung war erfolgreich, also hast du nutzbares outputData, aber mindestens eine nicht kritische Stufe hat einen failed-Eintrag und eine passende Warnung hinterlassen. Behandle das Ergebnis als auslieferbar und die Warnungen als Qualitätssignal, das du sichtbar machen solltest. Nur ein Job-status von failed bedeutet, dass es keine Übersetzung zum Auslesen gibt – und diese Entscheidung inklusive kompletter Job-Status-Tabelle findest du auf der Seite zum Einzeljob.

Nächste Schritte#