Criar jobs de localização

Crie um grupo de jobs de localização: uma única solicitação que distribui seu conteúdo para todos os idiomas de destino que você informar.

Você tem um payload de strings e uma lista de idiomas, e quer traduzir tudo sem precisar implementar essa distribuição por conta própria. POST /jobs/localization recebe o payload completo e até 100 idiomas de destino em uma única solicitação, depois retorna 202 Accepted imediatamente com um ID de grupo e um job por idioma. Uma solicitação, 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 da solicitação, a resposta 202 e como tornar a chamada segura para novas tentativas. Está começando com localização assíncrona? Comece pela Visão geral da API de Localização Assíncrona para entender o modelo mental. Depois que um grupo existir, acompanhar um grupo de jobs mostra o que significa o status de cada idioma.

Parâmetros#

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

Solicitação#

O campo data aceita pares simples de chave e valor ou estruturas aninhadas com objetos e arrays em qualquer profundidade. O engine traduz cada valor de string, preserva valores que não são string (números, booleanos, null) sem alteração e retorna exatamente a mesma estrutura que você enviou. Assim, você pode passar o mesmo objeto que seu app já armazena — sem achatar nem reestruturar.

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

Esse payload aninhado mistura texto traduzível com valores que precisam permanecer intactos — id, course_101, difficulty. As strings são traduzidas; o restante é preservado por tipo. Quando você também precisar segurar uma string (um slug, uma URL de asset, um código de enum), informe-a em lockedKeys e ela será mesclada de volta literalmente na saída de cada idioma.

Resposta (202 Accepted)#

A chamada retorna imediatamente. Ela não espera a tradução — entrega 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 para rodar. O que cada status significa à medida que os jobs avançam — e o que acontece quando um idioma falha enquanto os outros seguem adiante — está em Track a job group.

Exemplos#

A mesma solicitação em Node e Python. Ambos fazem um único POST e leem o ID do grupo e a quantidade de jobs direto 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 tentar de novo#

O lugar natural para disparar essa solicitação é um hook de salvamento ou um manipulador de eventos — exatamente o tipo de código que roda duas vezes quando acontece 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.

Envie um idempotencyKey e isso deixa de ser um risco. Envie a mesma solicitação duas vezes com a mesma chave e a plataforma retorna o grupo existente em vez de criar um novo — sem um segundo conjunto de jobs. As chaves têm escopo por engine, então a mesma chave em um engine 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 POST que distribui um payload para todos os idiomas, e é seguro dispará-lo a partir do mesmo fluxo de código que faz novas tentativas. Guarde o groupId; é isso que você vai usar em acompanhamento e progresso em tempo real.

Próximos passos#