Criar jobs de localização

Crie um grupo de jobs de localização: um único pedido que distribui o seu conteúdo por todos os idiomas de destino que indicar.

Tem uma payload de strings e uma lista de idiomas, e quer traduzi-las todas sem ter de implementar essa distribuição. POST /jobs/localization recebe a payload completa e até 100 idiomas de destino num único pedido, e devolve 202 Accepted de imediato com um ID de grupo e um job por idioma. Um pedido, todos os idiomas — a plataforma cria os jobs e processa cada um de forma independente.

POST /jobs/localization

Esta página cobre a chamada de criação: os parâmetros, o formato do pedido, a resposta 202 e como tornar a chamada segura para repetir. É novo na localização assíncrona? Comece pela Visão geral da API de Localização Assíncrona para perceber o modelo mental. Assim que existir um grupo, acompanhar um grupo de jobs mostra-lhe o que significa o estado de cada idioma.

Parâmetros#

sourceLocale, targetLocales e data são obrigatórios. Tudo o resto ajusta o comportamento ou torna a chamada mais segura de repetir.

Pedido#

O campo data aceita pares chave-valor simples ou estruturas aninhadas com objetos e arrays a qualquer profundidade. O motor traduz todos os valores string, preserva os valores que não são string (números, booleanos, null) sem alterações e devolve exatamente a estrutura que enviou. Assim, pode passar-lhe o mesmo objeto que a sua aplicação já armazena — sem achatamento, sem reformatação.

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

Esta payload aninhada combina texto traduzível com valores que têm de permanecer intactos — id, course_101, difficulty. As strings são traduzidas; o resto é preservado por tipo. Quando também precisar de excluir uma string da tradução (um slug, um URL de recurso, um código enum), indique-a em lockedKeys e ela é reintegrada literalmente no resultado de cada idioma.

Resposta (202 Accepted)#

A chamada devolve imediatamente. Não espera pela tradução — entrega-lhe o ID do grupo e os IDs dos jobs por idioma, e depois a plataforma processa cada job de forma independente em segundo plano.

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

Entram três idiomas, saem três jobs, cada um em queued e pronto a arrancar. O que significa cada estado à medida que os jobs avançam — e o que acontece quando um idioma falha enquanto os outros seguem em frente — está em Track a job group.

Exemplos#

O mesmo pedido em Node e Python. Ambos fazem um único POST e leem o ID do grupo e o número de jobs diretamente de 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

Torne a chamada segura para repetir#

O local natural para disparar este pedido é um save hook ou um processador de eventos — exatamente o tipo de código que corre duas vezes quando há uma nova tentativa ou chega um evento duplicado. Sem proteção, duas chamadas significam dois grupos de jobs, e o mesmo conteúdo entra na fila de tradução duas vezes.

Passe um idempotencyKey e isso deixa de ser um risco. Envie o mesmo pedido duas vezes com a mesma chave e a plataforma devolve o grupo existente em vez de criar um novo — sem um segundo conjunto de jobs. As chaves têm âmbito por motor, por isso a mesma chave usada com um motor diferente corresponde a um grupo diferente.

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

Este é o único POST que distribui uma payload por todos os idiomas, e é seguro dispará-lo a partir do mesmo caminho de código que faz novas tentativas. Guarde o groupId; é isso que vai usar no acompanhamento e no progresso em tempo real.

Passos seguintes#