Создать задачи локализации

Создайте группу задач локализации: один запрос — и ваш контент уйдёт во все указанные целевые локали.

У вас есть payload со строками и список локалей, и вы хотите перевести всё сразу, не реализуя fan-out самостоятельно. POST /jobs/localization принимает весь payload и до 100 целевых локалей в одном запросе, а затем сразу возвращает 202 Accepted с идентификатором группы и одной задачей на каждую локаль. Один запрос — все локали: платформа сама создаёт задачи и обрабатывает каждую независимо.

POST /jobs/localization

На этой странице разобран вызов создания: его параметры, формат запроса, ответ 202 и то, как сделать вызов безопасным для повторных попыток. Впервые работаете с асинхронной локализацией? Начните с обзора Async Localization API, чтобы понять общую модель. Когда группа уже создана, страница отслеживания группы задач поможет разобраться, что означает статус каждой локали.

Параметры#

sourceLocale, targetLocales и data обязательны. Всё остальное настраивает поведение или делает повторный вызов безопаснее.

Запрос#

Поле data принимает как плоские пары ключ-значение, так и вложенные структуры с объектами и массивами любой глубины. Движок переводит каждое строковое значение, оставляет нестроковые значения (числа, булевы значения, null) без изменений и возвращает ровно ту же структуру, которую вы отправили. То есть можно передать тот же объект, который уже хранит ваше приложение, — без выравнивания и без преобразования структуры.

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

Этот вложенный payload сочетает переводимый текст со значениями, которые должны остаться без изменений — id, course_101, difficulty. Строки переводятся, всё остальное сохраняется в исходном типе. Если нужно исключить из перевода и строку тоже (slug, URL ресурса, код enum), укажите её в lockedKeys, и она будет дословно возвращена в результат для каждой локали.

Ответ (202 Accepted)#

Вызов возвращает результат сразу. Он не ждёт завершения перевода — вместо этого вы получаете идентификатор группы и идентификаторы задач для каждой локали, а затем платформа обрабатывает каждую задачу независимо в фоне.

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

Три локали на входе — три задачи на выходе, каждая в статусе queued и готова к запуску. Что означает каждый статус по мере выполнения задач — и что происходит, если одна локаль завершается с ошибкой, пока остальные успешно выходят, — описано на странице Track a job group.

Примеры#

Один и тот же запрос на Node и Python. В обоих случаях отправляется один POST-запрос, а идентификатор группы и количество задач читаются прямо из 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

Как сделать вызов безопасным для повторных попыток#

Обычно такой запрос отправляют из save hook или обработчика событий — то есть именно из того кода, который легко может выполниться дважды при повторной попытке или при получении дубликата события. Без защиты два вызова означают две группы задач, а один и тот же контент дважды уходит в очередь на перевод.

Передайте idempotencyKey, и этот риск исчезнет. Если отправить один и тот же запрос дважды с тем же ключом, платформа вернёт существующую группу вместо создания новой — без второго набора задач. Ключи действуют в рамках одного движка, поэтому тот же ключ для другого движка означает уже другую группу.

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

Это тот самый POST-запрос, который отправляет один payload сразу во все локали, и его безопасно вызывать из того же участка кода, где возможны повторы. Сохраните groupId — именно его вы будете использовать для отслеживания и просмотра прогресса в реальном времени.

Что дальше#