Crear trabajos de localización

Crea un grupo de trabajos de localización: una sola solicitud que distribuye tu contenido a cada idioma de destino que indiques.

Tienes una carga útil de cadenas y una lista de idiomas, y quieres traducirlo todo sin tener que implementar tú mismo esa distribución. POST /jobs/localization acepta la carga útil completa y hasta 100 idiomas de destino en una sola solicitud, y devuelve 202 Accepted al instante con un ID de grupo y un trabajo por idioma. Una sola solicitud, todos los idiomas: la plataforma crea los trabajos y procesa cada uno por separado.

POST /jobs/localization

Esta página cubre la llamada de creación: sus parámetros, el formato de la solicitud, la respuesta 202 y cómo hacer que la llamada sea segura de reintentar. ¿Acabas de llegar a la localización asíncrona? Empieza por la Descripción general de la API de localización asíncrona para hacerte con el modelo mental. Una vez exista un grupo, seguimiento de un grupo de trabajos te explica qué significa el estado de cada idioma.

Parámetros#

sourceLocale, targetLocales y data son obligatorios. Todo lo demás ajusta el comportamiento o hace que la llamada sea más segura de repetir.

Solicitud#

El campo data acepta pares clave-valor planos o estructuras anidadas con objetos y arrays a cualquier profundidad. El motor traduce cada valor de tipo cadena, deja intactos los valores que no son cadenas (números, booleanos, null) y devuelve exactamente la misma estructura que enviaste. Así que puedes pasarle el mismo objeto que ya almacena tu aplicación: sin aplanarlo ni remodelarlo.

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

Esa carga útil anidada mezcla texto traducible con valores que deben mantenerse intactos: id, course_101, difficulty. Las cadenas se traducen; el resto se conserva por tipo. Cuando también necesitas excluir una cadena de la traducción (un slug, una URL de recurso o un código de enumeración), indícala en lockedKeys y se reintegrará literalmente en la salida de cada idioma.

Respuesta (202 Accepted)#

La llamada devuelve el resultado de inmediato. No espera a que termine la traducción: te entrega el ID de grupo y los ID de trabajo por idioma, y después la plataforma procesa cada trabajo de forma independiente en 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"
}

Tres idiomas de entrada, tres trabajos de vuelta: cada uno en estado queued y listo para ejecutarse. El significado de cada estado a medida que avanzan los trabajos —y qué ocurre cuando un idioma falla mientras los demás salen adelante— se explica en Track a job group.

Ejemplos#

La misma solicitud desde Node y Python. Ambos lanzan un único POST y leen el ID de grupo y el número de trabajos directamente 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

Haz que la llamada sea segura de reintentar#

El lugar natural para lanzar esta solicitud es un hook de guardado o un controlador de eventos: justo el tipo de código que se ejecuta dos veces cuando salta un reintento o llega un evento duplicado. Sin protección, dos llamadas significan dos grupos de trabajos, y el mismo contenido se pone en cola para traducirse dos veces.

Pasa un idempotencyKey y ese riesgo desaparece. Envía la misma solicitud dos veces con la misma clave y la plataforma devolverá el grupo existente en lugar de crear uno nuevo: sin un segundo lote de trabajos. Las claves tienen ámbito por motor, así que la misma clave contra un motor distinto corresponde a un 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 es el POST que distribuye una carga útil a todos los idiomas, y es seguro lanzarlo desde la misma ruta de código que gestiona reintentos. Guarda el groupId; es lo que usarás después para el seguimiento y el progreso en tiempo real.

Siguientes pasos#