Lokalisierungsjobs erstellen

Erstelle eine Lokalisierungs-Jobgruppe: eine einzige Anfrage, die deine Inhalte auf alle angegebenen Zielsprachen verteilt.

Du hast eine Payload mit Strings und eine Liste von Sprachen und willst alles übersetzen, ohne das Fan-out selbst zu bauen. POST /jobs/localization nimmt die komplette Payload und bis zu 100 Zielsprachen in einer einzigen Anfrage entgegen und gibt sofort 202 Accepted mit einer Gruppen-ID und einem Job pro Sprache zurück. Eine Anfrage, alle Sprachen – die Plattform legt die Jobs an und verarbeitet sie unabhängig voneinander.

POST /jobs/localization

Auf dieser Seite geht es um den Erstellungsaufruf: die Parameter, das Anfrageformat, die Antwort 202 und darum, wie du den Aufruf sicher wiederholbar machst. Neu bei asynchroner Lokalisierung? Starte mit dem Überblick über die Async Localization API, um das Grundmodell zu verstehen. Sobald eine Gruppe existiert, zeigt dir Eine Jobgruppe nachverfolgen, was der Status jeder Sprache bedeutet.

Parameter#

sourceLocale, targetLocales und data sind erforderlich. Alles andere steuert das Verhalten oder macht den Aufruf sicherer für Wiederholungen.

Anfrage#

Das Feld data akzeptiert flache Schlüssel-Wert-Paare oder verschachtelte Strukturen mit Objekten und Arrays in beliebiger Tiefe. Die Engine übersetzt jeden String-Wert, lässt Nicht-String-Werte (Zahlen, Booleans, null) unverändert und gibt exakt die Struktur zurück, die du gesendet hast. Du kannst also genau dasselbe Objekt übergeben, das deine App bereits speichert – kein Flattening, kein Umformen.

{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr", "ja"],
  "data": {
    "lesson_title": "Introduction to Machine Learning",
    "lesson_summary": "This lesson covers the fundamentals of ML, including supervised and unsupervised learning."
  },
  "callbackUrl": "https://your-app.com/webhooks/translations",
  "idempotencyKey": "course_101-v3"
}

Diese verschachtelte Payload mischt übersetzbaren Text mit Werten, die unverändert erhalten bleiben müssen – id, course_101, difficulty. Strings werden übersetzt, alles andere bleibt typgetreu erhalten. Wenn du auch einen String ausnehmen musst (etwa einen Slug, eine Asset-URL oder einen Enum-Code), gib ihn in lockedKeys an, dann wird er unverändert in die Ausgabe jeder Sprache zurückgeführt.

Antwort (202 Accepted)#

Der Aufruf liefert sofort eine Antwort. Er wartet nicht auf die Übersetzung – stattdessen bekommst du die Gruppen-ID und die Job-IDs pro Sprache, während die Plattform jeden Job unabhängig im Hintergrund verarbeitet.

{
  "groupId": "ljg_A1b2C3d4E5f6G7h8",
  "status": "pending",
  "jobs": [
    { "id": "ljb_A1b2C3d4E5f6G7h8", "targetLocale": "de", "status": "queued" },
    { "id": "ljb_B2c3D4e5F6g7H8i9", "targetLocale": "fr", "status": "queued" },
    { "id": "ljb_C3d4E5f6G7h8I9j0", "targetLocale": "ja", "status": "queued" }
  ],
  "createdAt": "2026-03-16T10:30:00.000Z"
}

Drei Sprachen rein, drei Jobs zurück – jeweils queued und startklar. Was die einzelnen Status bedeuten, während die Jobs voranschreiten – und was passiert, wenn eine Sprache fehlschlägt, während die anderen ausgeliefert werden – erfährst du unter Track a job group.

Beispiele#

Dieselbe Anfrage in Node und Python. Beide schicken genau ein POST ab und lesen Gruppen-ID und Jobanzahl direkt aus 202 aus.

const response = await fetch("https://api.lingo.dev/jobs/localization", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.LINGO_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    sourceLocale: "en",
    targetLocales: ["de", "fr", "ja"],
    data: {
      title: "Introduction to Machine Learning",
      steps: [
        { heading: "What is ML?", body: "Machine learning is a subset of AI." },
        { heading: "Supervised Learning", body: "Training with labeled data." },
      ],
    },
    callbackUrl: "https://your-app.com/webhooks/translations",
  }),
});

const { groupId, jobs } = await response.json();
// 202 Accepted – the call returns without waiting for translation.
console.log(groupId);     // "ljg_A1b2C3d4E5f6G7h8"
console.log(jobs.length); // 3 – one queued job per target locale

Den Aufruf sicher wiederholbar machen#

Der naheliegende Ort für diese Anfrage ist ein Save-Hook oder ein Event-Handler – also genau der Code, der doppelt läuft, wenn ein Retry ausgelöst wird oder ein dupliziertes Event eintrifft. Ohne Absicherung bedeuten zwei Aufrufe zwei Jobgruppen, und derselbe Inhalt landet zweimal in der Übersetzungswarteschlange.

Gib ein idempotencyKey mit, und dieses Risiko entfällt. Wenn du dieselbe Anfrage zweimal mit demselben Schlüssel sendest, gibt die Plattform die bestehende Gruppe zurück, statt eine neue zu erstellen – ohne zweiten Satz Jobs. Schlüssel gelten pro Engine. Derselbe Schlüssel gegen eine andere Engine ergibt also eine andere Gruppe.

const key = `${content.id}-v${content.version}`;

async function submit() {
  const response = await fetch("https://api.lingo.dev/jobs/localization", {
    method: "POST",
    headers: {
      "X-API-Key": process.env.LINGO_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      sourceLocale: "en",
      targetLocales: ["de", "fr", "ja", "ko", "pt-BR"],
      data: { title: content.title, steps: content.steps },
      callbackUrl: "https://your-app.com/webhooks/translations",
      idempotencyKey: key,
    }),
  });
  return (await response.json()).groupId;
}

const first = await submit();
const again = await submit(); // same key – duplicate submission
console.log(first === again); // true – same group returned, no second set of jobs

Das ist das eine POST, das eine Payload auf alle Sprachen verteilt – und das du sicher aus demselben Codepfad auslösen kannst, der auch Retries verarbeitet. Speichere groupId; genau das brauchst du später für Tracking und Live-Fortschritt.

Nächste Schritte#