Vytváření lokalizačních úloh

Vytvořte skupinu lokalizačních úloh: jediný požadavek, který rozešle váš obsah do všech cílových jazyků, které zadáte.

Máte payload řetězců a seznam jazyků a chcete je všechny přeložit, aniž byste si fan-out řešili sami. POST /jobs/localization vezme celý payload a až 100 cílových jazyků v jediném požadavku a hned vrátí 202 Accepted s ID skupiny a jednou úlohou pro každý jazyk. Jeden požadavek, všechny jazyky – platforma vytvoří úlohy a každou zpracuje nezávisle.

POST /jobs/localization

Tato stránka pokrývá volání pro vytvoření: jeho parametry, podobu požadavku, odpověď 202 i to, jak zajistit bezpečné opakování volání. S asynchronní lokalizací teprve začínáte? Začněte u Přehled Async Localization API, kde získáte základní mentální model. Jakmile skupina existuje, sledování skupiny úloh vám ukáže, co znamená stav každého jazyka.

Parametry#

sourceLocale, targetLocales a data jsou povinné. Všechno ostatní upravuje chování nebo dělá opakování volání bezpečnější.

Požadavek#

Pole data přijímá ploché dvojice klíč–hodnota i vnořené struktury s objekty a poli v libovolné hloubce. engine přeloží každou řetězcovou hodnotu, neřetězcové hodnoty (čísla, booleany, null) nechá beze změny a vrátí přesně stejnou strukturu, jakou jste poslali. Můžete mu tedy předat stejný objekt, který už vaše aplikace ukládá – bez zplošťování a bez změny struktury.

{
  "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"
}

Tento vnořený payload kombinuje přeložitelný text s hodnotami, které musí zůstat beze změny – id, course_101, difficulty. Řetězce se překládají, všechno ostatní se zachová podle typu. Když potřebujete z překladu vynechat i řetězec (slug, URL assetu, kód enumu), uveďte ho v lockedKeys a beze změny se znovu sloučí do výstupu pro každý jazyk.

Odpověď (202 Accepted)#

Volání se vrátí okamžitě. Na překlad nečeká – předá vám ID skupiny a ID úloh pro jednotlivé jazyky a platforma pak každou úlohu zpracovává nezávisle na pozadí.

{
  "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"
}

Tři jazyky dovnitř, tři úlohy ven, každá ve stavu queued a připravená ke spuštění. Co jednotlivé stavy znamenají v průběhu zpracování úloh – a co se stane, když jeden jazyk selže, zatímco ostatní pokračují dál – najdete na stránce Track a job group.

Příklady#

Stejný požadavek v Node i Pythonu. V obou případech odešlete jeden POST a ID skupiny i počet úloh přečtete rovnou z 202.

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

Jak zajistit bezpečné opakování volání#

Tohle volání se přirozeně hodí do save hooku nebo event handleru – tedy přesně do kódu, který se spustí dvakrát, když přijde retry nebo duplicitní událost. Bez ochrany znamenají dvě volání dvě skupiny úloh a stejný obsah se zařadí k překladu dvakrát.

Pošlete idempotencyKey a tohle riziko zmizí. Když odešlete stejný požadavek dvakrát se stejným klíčem, platforma vrátí existující skupinu místo vytvoření nové – bez druhé sady úloh. Klíče platí samostatně pro každý engine, takže stejný klíč použitý s jiným engine znamená jinou skupinu.

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

Tohle je ten jediný POST, který rozešle payload do všech jazyků, a můžete ho bezpečně spouštět ze stejné cesty v kódu, která řeší retry. Uložte si groupId; právě ten pak použijete pro sledování i živý průběh.

Další kroky#