Hintergrundübersetzung aller veröffentlichten Dokumente aus einem oder mehreren Komponentenschemas in eine Reihe von Zielsprachen in die Warteschlange einreihen. Die Ergebnisse werden nach Abschluss jeder Übersetzung in die Tabelle translations eingefügt oder dort aktualisiert.

Endpunkt: POST /translation Authentifizierung: Bearer-JWT (WorkOS)

Anfragekörper

{
  "websiteId": "<uuid>",
  "schemaNames": ["post", "hero"],
  "languages": ["fr", "es", "de"]
}

* Entweder schemaNames oder schemaName angeben.

Es werden nur veröffentlichte Dokumente mit nicht-leerem veröffentlichtem Inhalt berücksichtigt.

Antwort

{
  "job_id": "<uuid>",
  "website_id": "<uuid>",
  "schema_name": null,
  "schema_names": ["post", "hero"],
  "languages": ["fr", "es", "de"],
  "status": "queued",
  "documents_processed": 12,
  "translations_scheduled": 30,
  "translations_skipped": 6,
  "translations_completed": 0,
  "translations_failed": 0,
  "reused": false,
  "created_at": "2026-07-15T18:00:00Z",
  "updated_at": "2026-07-15T18:00:00Z"
}

Rückgabewerte:

• 202 Accepted, wenn Übersetzungen in die Warteschlange eingereiht wurden
• 200 OK, wenn jede Übersetzung bereits aktuell ist
• der bestehende aktive Auftrag, wenn bereits eine identische Anfrage ausgeführt wird

Mögliche Auftragsstatus sind:

• preparing
• queued
• running
• completed
• completed_with_errors
• failed

Überspringen aktueller Übersetzungen

Jedes Dokument-Sprach-Paar speichert einen SHA-256-Hash des veröffentlichten Inhalts des Quelldokuments.

Eine Übersetzung wird übersprungen, wenn der gespeicherte Quell-Hash mit dem aktuellen veröffentlichten Inhalt übereinstimmt. Dadurch kann der Endpunkt wiederholt aufgerufen werden, ohne unveränderte Inhalte erneut zu übersetzen.

Wenn sich der veröffentlichte Inhalt ändert, während ein gleichwertiger Auftrag aktiv ist, lehnt der Dienst die neue Anfrage ab. Reichen Sie sie erneut ein, nachdem der aktive Auftrag abgeschlossen ist.

Verarbeitungsverhalten

Die Übersetzung wird nach der ersten Antwort asynchron ausgeführt.

• Die Verarbeitung erfolgt mit begrenzter Nebenläufigkeit.
• Vorübergehende Fehler werden mit Backoff erneut versucht.
• Erfolgreiche Ergebnisse werden nach ihrem Abschluss gespeichert.
• Einzelne Fehler bei der Inferenz oder Persistierung werden im Auftrag erfasst.
• Ein teilweise erfolgreicher Auftrag wird mit completed_with_errors abgeschlossen.

Beispiel

curl -X POST '{TRANSLATION_API_URL}/translation' \
  -H 'Authorization: Bearer <workos-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{
    "websiteId": "<uuid>",
    "schemaNames": ["post", "hero"],
    "languages": ["fr", "es"]
  }'

Fehler

• 400 Bad Request — Schemas oder Sprachen fehlen, eine Sprache wird nicht unterstützt oder der Batch überschreitet das konfigurierte Limit
• 401 Unauthorized — Bearer-Token fehlt oder ist ungültig
• 409 Conflict — Eine passende Verarbeitung ist aktiv, aber der veröffentlichte Quellinhalt hat sich geändert
• 500 Internal Server Error — Quelldokumente konnten nicht vorbereitet werden oder ein Datenbankvorgang ist fehlgeschlagen

Übersetzungsauftrag abrufen

Den aktuellen Fortschritt eines Übersetzungsauftrags abrufen.

Endpunkt: GET /translation-jobs/{job_id} Authentifizierung: Bearer-JWT (WorkOS)

Antwort

Die Antwort verwendet dasselbe Auftragsobjekt wie POST /translation, mit aktualisiertem Status und aktualisierten Fortschrittszählern.

{
  "job_id": "<uuid>",
  "website_id": "<uuid>",
  "schema_name": null,
  "schema_names": ["post", "hero"],
  "languages": ["fr", "es"],
  "status": "running",
  "documents_processed": 12,
  "translations_scheduled": 24,
  "translations_skipped": 0,
  "translations_completed": 16,
  "translations_failed": 1,
  "reused": false,
  "created_at": "2026-07-15T18:00:00Z",
  "updated_at": "2026-07-15T18:01:30Z"
}

Beispiel

curl '{TRANSLATION_API_URL}/translation-jobs/<job-id>' \
  -H 'Authorization: Bearer <workos-jwt>'

Fehler

• 401 Unauthorized — Bearer-Token fehlt oder ist ungültig
• 404 Not Found — Der Auftrag existiert nicht oder wird nicht mehr aufbewahrt

Übersetzungsaufträge werden derzeit im Arbeitsspeicher aufbewahrt. Der Auftragsstatus geht verloren, wenn der Übersetzungsdienst neu gestartet wird, und Bereitstellungen mit mehreren Instanzen erfordern Sticky Routing.