Získání jednoho jobu

Přečtěte si přeložený výstup pro jeden jazyk i záznam jednotlivých fází, jak vznikl.

Po tomhle sáhnete ve chvíli, kdy už máte jobId – vrácené v 202 z create, doručené ve webhooku nebo uvedené ve skupině jobů. Endpoint skupiny vám řekne, kolik jazyků je hotových. Tento endpoint vám řekne, co vzniklo pro jeden konkrétní jazyk a co se dělo po cestě.

text

GET /jobs/localization/:jobId

Jste v asynchronní lokalizaci noví? Začněte s Přehled.

Právě v tom spočívá smysl celé této stránky. Odpověď skupiny je výsledková tabule – počty a stav jednotlivých jobů, popsané na stránce o skupině jobů. Jeden job je úplný záznam pro jeden jazyk: přeložené outputData, finální status, případné warnings a stopa v steps[] všech fází, které běžely v pipeline. Až budete chtít zapsat německý text do databáze, právě tohle volání vám ho vrátí.

Ověření#

Předejte svůj API klíč v hlavičce X-API-Key. Klíče platí pro celou organizaci a dávají přístup ke každému engine v organizaci. Podrobnosti najdete v Authentication.

Odpověď#

Pole outputData kopíruje strukturu vstupních data: každá řetězcová hodnota je přeložená a každá neřetězcová hodnota (čísla, booleany, null) zůstává na svém místě beze změny. Stejné klíče, stejné vnoření, stejné pořadí v poli – mění se jen řetězce.

json

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

Blok metadata výše zůstal beze změny – Dr. Smith a beginner jsou neřetězcové listy, které engine ponechal tak, jak jsou. outputData, které dostanete zpět, odpovídá tvaru, který jste odeslali, takže stejný kód, který payload sestavil, může zpracovat i překlad.

Pole	Popis
`id`	ID tohoto jobu (`ljb_…`). Hodnota, kterou jste předali v cestě.
`groupId`	Nadřazená skupina jobů (`ljg_…`), do které tento job patří. Předejte ji do endpointu skupiny jobů, pokud chcete najednou vidět všechny související jazyky.
`targetLocale`	BCP-47 jazyk, do kterého tento job překládal – pro každý cílový jazyk existuje jeden job. Podle tohoto pole větvíte logiku, abyste `outputData` poslali do správného sloupce nebo souboru.
`status`	`queued`, `processing`, `completed`, `completed_with_warnings` nebo `failed`.
`outputData`	Přeložený obsah odpovídající vstupní struktuře. Je přítomný, když je `status` `completed` nebo `completed_with_warnings`.
`errorMessage`	Popis chyby. Je přítomný, když je `status` `failed`, jinak `null`.
`warnings`	Nekritická selhání fází pipeline. Každá položka je `{ step, message }`. Pole je prázdné, pokud `status` není `completed_with_warnings`.
`callbackStatus`	Stav doručení webhooku: `pending`, `delivered` nebo `failed`. `null`, pokud není nakonfigurovaná callback URL.
`createdAt`	Kdy byl job přijat (časové razítko na `202`, které ho vytvořilo).
`startedAt`	Kdy engine začal překládat tento jazyk. Nastaví se, jakmile job opustí stav `queued`.
`completedAt`	Kdy job dosáhl finálního stavu. Nastaví se, jakmile je `status` `completed`, `completed_with_warnings` nebo `failed`.
`steps`	Záznamy o běhu jednotlivých fází. Vždy obsahuje krok `localize` plus jednu položku za každou aktivní nepovinnou fázi pipeline. Úplný tvar záznamu najdete v Observe pipeline runs.

outputData je null, dokud job neskončí

Dokud je status queued nebo processing, je outputData prázdné a errorMessage je null – zatím není co číst. outputData čtěte až ve chvíli, kdy status dosáhne completed nebo completed_with_warnings; při failed místo toho čtěte errorMessage. Nejdřív větvěte podle status, teprve potom sahajte na payload.

Hodnoty stavu jobu#

Job přechází z queued do processing a potom do přesně jednoho finálního stavu. Než začnete číst cokoli dalšího, větvěte podle status – právě to určuje, která pole jsou vyplněná.

Stav	Význam	Co číst
`queued`	Přijato, ale ještě nezačalo.	Zatím nic – pollujte nebo počkejte na webhook.
`processing`	Engine právě překládá tento jazyk.	Zatím nic.
`completed`	Překlad je hotový, všechny aktivní fáze doběhly úspěšně.	`outputData`.
`completed_with_warnings`	Překlad je hotový a `outputData` je kompletní, ale jedna nekritická fáze pipeline nedoběhla úspěšně.	`outputData`, potom `warnings`.
`failed`	Job nevytvořil žádný překlad.	`errorMessage`.

completed_with_warnings stále vrací překlad

completed_with_warnings není měkké selhání. Dostanete plné outputData – hlavní krok překladu proběhl úspěšně. Změnilo se jen to, že některá nekritická fáze (například pre-edit nebo back-translation) nedoběhla a každé selhání je zaznamenané v warnings jako { step, message }. Výstup berte jako použitelný; warnings berte jako signál kvality, který stojí za to ukázat tomu, kdo provádí kontrolu překladů. Jen failed znamená, že není žádný překlad ke čtení.

Počítejte i s neznámými hodnotami stavu

Výše uvedených pět hodnot stavu je dnešní kontrakt. Fáze pipeline se vyvíjejí, takže s status zacházejte jako s otevřenou množinou: větvěte podle hodnot, které znáte, a všechno neočekávané směrujte do výchozí větve, která přečte outputData, pokud je k dispozici, a jinak zapíše do logu. switch bez fallbacku je přesně ten řádek, který se rozbije v den, kdy přibude nový stav.

Pole steps#

steps[] je stopa jednotlivých fází za jedním jobem – jeden záznam pro každou fázi, kterou engine spustil, ve správném pořadí. Každý job obsahuje alespoň krok localize, protože základní překlad běží vždy. Každá nepovinná fáze pipeline, kterou jste aktivovali, přidá další záznam. Job bez dalších fází tedy obsahuje jen krok localize; job s aktivními pre-edit a back-translation jich obsahuje tři.

Právě to dělá z jobu auditovatelný záznam místo černé skříňky. Nemusíte jen věřit, že fáze proběhla – můžete si přečíst její záznam: o kterou fázi šlo (stepId), jestli completed, failed nebo byla skipped, kolik stála (costUsd) a kdy začala a skončila. U fází s lidskou kontrolou ukazuje externalRef* na externí záznam.

json

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

Položka failed tady nemusí nutně znamenat selhání jobu. Když selže nekritická fáze, její záznam steps[] má hodnotu failed, stejné selhání se projeví i v poli warnings na nejvyšší úrovni jobu a job přesto skončí ve stavu completed_with_warnings s plným outputData. Úplný tvar záznamu – každé pole, každý stepId, význam completed/failed/skipped – najdete na jediné kanonické stránce: Observe pipeline runs. Tato stránka ukazuje, kde to u jobu najít; tamta stránka to přesně specifikuje.

Čtení dokončeného jobu#

Typický konzument větví podle status, při úspěchu zapisuje outputData a při selhání zapisuje errorMessage do logu. Volání níže připravené ke zkopírování vrací payload zobrazený výše.

javascript

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

Tento endpoint vrací stav v konkrétním okamžiku. U většiny jobů trvá engine 2–8 sekund na jazyk, takže pokud pollujete, interval 2 sekund je rozumný začátek. Pokud se chcete pollingu úplně vyhnout, zaregistrujte webhook a job načítejte jen tehdy, když vám oznámí, že je jazyk hotový, nebo sledujte celou skupinu přes WebSocket. Ať už zvolíte kteroukoli možnost, finální GET je tady kanonické čtení outputData.

Když tento endpoint vrátí chybu – neznámé jobId, chybějící klíč – řídí se standardním JSON modelem chyb. Viz Errors and status codes.

Další kroky#

Sledovat skupinu jobů

Zobrazte si souhrnné počty a řešte částečná selhání napříč všemi jazyky

Vypsat joby

Procházejte joby po stránkách pomocí kurzorové paginace a filtrujte podle stavu nebo engine

Průběh živě (WebSocket)

Sledujte stav jednotlivých jazyků při dokončení každého jobu bez pollingu

Přečtěte si přeložený výstup pro jeden jazyk i záznam jednotlivých fází, jak vznikl.

text

GET /jobs/localization/:jobId

Jste v asynchronní lokalizaci noví? Začněte s Přehled.

Ověření#

Předejte svůj API klíč v hlavičce X-API-Key. Klíče platí pro celou organizaci a dávají přístup ke každému engine v organizaci. Podrobnosti najdete v Authentication.

Odpověď#

json

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

Pole	Popis
`id`	ID tohoto jobu (`ljb_…`). Hodnota, kterou jste předali v cestě.
`groupId`	Nadřazená skupina jobů (`ljg_…`), do které tento job patří. Předejte ji do endpointu skupiny jobů, pokud chcete najednou vidět všechny související jazyky.
`targetLocale`	BCP-47 jazyk, do kterého tento job překládal – pro každý cílový jazyk existuje jeden job. Podle tohoto pole větvíte logiku, abyste `outputData` poslali do správného sloupce nebo souboru.
`status`	`queued`, `processing`, `completed`, `completed_with_warnings` nebo `failed`.
`outputData`	Přeložený obsah odpovídající vstupní struktuře. Je přítomný, když je `status` `completed` nebo `completed_with_warnings`.
`errorMessage`	Popis chyby. Je přítomný, když je `status` `failed`, jinak `null`.
`warnings`	Nekritická selhání fází pipeline. Každá položka je `{ step, message }`. Pole je prázdné, pokud `status` není `completed_with_warnings`.
`callbackStatus`	Stav doručení webhooku: `pending`, `delivered` nebo `failed`. `null`, pokud není nakonfigurovaná callback URL.
`createdAt`	Kdy byl job přijat (časové razítko na `202`, které ho vytvořilo).
`startedAt`	Kdy engine začal překládat tento jazyk. Nastaví se, jakmile job opustí stav `queued`.
`completedAt`	Kdy job dosáhl finálního stavu. Nastaví se, jakmile je `status` `completed`, `completed_with_warnings` nebo `failed`.
`steps`	Záznamy o běhu jednotlivých fází. Vždy obsahuje krok `localize` plus jednu položku za každou aktivní nepovinnou fázi pipeline. Úplný tvar záznamu najdete v Observe pipeline runs.

outputData je null, dokud job neskončí

Hodnoty stavu jobu#

Stav	Význam	Co číst
`queued`	Přijato, ale ještě nezačalo.	Zatím nic – pollujte nebo počkejte na webhook.
`processing`	Engine právě překládá tento jazyk.	Zatím nic.
`completed`	Překlad je hotový, všechny aktivní fáze doběhly úspěšně.	`outputData`.
`completed_with_warnings`	Překlad je hotový a `outputData` je kompletní, ale jedna nekritická fáze pipeline nedoběhla úspěšně.	`outputData`, potom `warnings`.
`failed`	Job nevytvořil žádný překlad.	`errorMessage`.

completed_with_warnings stále vrací překlad

Počítejte i s neznámými hodnotami stavu

Pole steps#

json

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

Čtení dokončeného jobu#

javascript

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

Když tento endpoint vrátí chybu – neznámé jobId, chybějící klíč – řídí se standardním JSON modelem chyb. Viz Errors and status codes.

Další kroky#

Sledovat skupinu jobů

Zobrazte si souhrnné počty a řešte částečná selhání napříč všemi jazyky

Vypsat joby

Procházejte joby po stránkách pomocí kurzorové paginace a filtrujte podle stavu nebo engine

Průběh živě (WebSocket)

Sledujte stav jednotlivých jazyků při dokončení každého jobu bez pollingu