创建本地化任务

创建一个本地化任务组：一次请求，就能把内容分发到你指定的所有目标语言区域。

如果你手上有一份字符串 payload 和一组语言区域列表，希望一次性完成全部翻译，而不用自己写分发逻辑，POST /jobs/localization 就能在单次请求中接收完整 payload 和最多 100 个目标语言区域，并立即返回 202 Accepted，附带一个组 ID，以及每个语言区域对应的一个任务。一次请求，覆盖所有语言区域——平台会自动创建任务，并分别独立处理。

text

POST /jobs/localization

本页介绍创建调用本身：包括参数、请求结构、202 响应，以及如何让这次调用能够安全重试。第一次接触异步本地化？建议先看异步本地化 API 概览，先建立整体认知。任务组创建后，跟踪任务组会告诉你每个语言区域状态分别代表什么。

身份验证

请在 X-API-Key 请求头中传入你的 API 密钥。密钥作用域为组织级，可访问该组织下的所有引擎。详情请参见身份验证。

参数#

sourceLocale、targetLocales 和 data 为必填项，其余字段用于调整行为，或让调用在重复执行时更安全。

参数	类型	说明
`sourceLocale`	string	BCP-47 源语言区域（例如 `en`）。
`targetLocales`	string[]	BCP-47 目标语言区域（例如 `["de", "fr", "ja"]`）。每次请求可传 1–100 个。每个语言区域都会创建一个任务。
`data`	object	待翻译的键值内容。支持任意深度的嵌套对象和数组。
`context`	string（可选）	这份翻译 payload 的整体上下文，例如产品界面、目标受众或用途。会应用到本次请求创建的每一个任务。
`hints`	object（可选）	按 key 提供的上下文，以面包屑字符串数组表示，用于消除简短或复用字符串的歧义。
`callbackUrl`	string（可选）	此任务组的 HTTPS webhook URL。会覆盖组织默认值。不接受 HTTP。
`idempotencyKey`	string（可选）	客户端生成的键。用相同的键发送两次相同请求时，返回的是现有任务组，而不是新建一个。按引擎划分作用域。
`engineId`	string（可选）	用于执行这些任务的本地化引擎。若省略，则回退到组织的默认引擎。
`pipelineConfig`	object（可选）	按请求设置的 pipeline 覆盖项。未指定的阶段会继承引擎配置。
`lockedKeys`	string[]（可选）	值会被排除在翻译之外、并原样合并回 `outputData` 的 key 或 glob 模式。最多 100 个模式。参见锁定不可翻译的键。

请求#

data 字段既支持扁平键值对，也支持包含对象和数组、可任意深度嵌套的结构。引擎会翻译其中每一个字符串值，保留非字符串值（数字、布尔值、null）不变，并按你传入的原始结构返回结果。所以你可以直接把应用当前存储的对象交给它——不用拍平，也不用改结构。

json

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

必须使用 HTTPS

callbackUrl 必须使用 HTTPS。HTTP URL 会被拒绝，并返回 400 错误。

这个嵌套 payload 同时包含可翻译文本，以及必须原样保留的值——id、course_101、difficulty。字符串会被翻译；其余内容会按原始类型保留。如果你还需要让某个 字符串 也不参与翻译（例如 slug、资源 URL 或枚举代码），就在 lockedKeys 中指定它，它就会原样合并回每个语言区域的输出结果。

响应（202 Accepted）#

调用会立即返回，不会等待翻译完成——它会先把组 ID 和各语言区域的任务 ID 返回给你，随后平台会在后台独立处理每个任务。

json

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

字段	说明
`groupId`	整个任务组的标识符，带有 `ljg_` 前缀。请保存它——后续跟踪和查看实时进度都要靠它。
`status`	任务组创建时的状态，通常为 `pending`。
`jobs`	每个目标语言区域对应一条记录：`id`（带有 `ljb_` 前缀）、`targetLocale`，以及该任务的 `status`。
`createdAt`	ISO 8601 时间戳。

传入三个语言区域，就会返回三个任务；每个任务都处于 queued 状态，随时可以开始执行。随着任务推进，每种状态具体代表什么——以及当某个语言区域失败、其他语言区域仍然成功交付时会发生什么——请参见跟踪任务组。

示例#

下面分别展示 Node 和 Python 的同一请求。两者都只发送一次 POST，并直接从 202 中读取组 ID 和任务数量。

javascript

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

让调用可安全重试#

最适合触发这类请求的地方，往往是保存钩子或事件处理器——而这也正是发生重试或收到重复事件时最容易执行两次的代码。如果没有保护，两次调用就意味着两个任务组，同一份内容也会被重复排队翻译两次。

传入 idempotencyKey 后，这个风险就不存在了。用相同的键发送两次相同请求时，平台返回的是现有任务组，而不是重新创建一个——不会产生第二批任务。键按引擎划分作用域，因此同一个键如果用于不同引擎，对应的就是不同任务组。

选择一个有意义的键

一个好的键，应该把内容标识和版本组合起来：{contentId}-v{contentVersion}。同一份内容的同一版本，总会解析到同一个任务组，因此重试天然就是空操作。内容一旦变化，只要提升版本号，就会得到一个新的任务组。

javascript

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；后续做跟踪和查看实时进度时，你都要用到它。

后续步骤#

锁定不可翻译的键

通过 key 和 glob 模式，让 ID、slug、资源 URL 和枚举代码不参与翻译。

配置 pipeline

按请求覆盖 pipeline 各阶段，或设置每个任务都会继承的引擎级默认值。

跟踪任务组

查看任务组和各语言区域的状态，并处理某个语言区域失败而其余语言区域成功交付的情况。

创建一个本地化任务组：一次请求，就能把内容分发到你指定的所有目标语言区域。

text

POST /jobs/localization

身份验证

请在 X-API-Key 请求头中传入你的 API 密钥。密钥作用域为组织级，可访问该组织下的所有引擎。详情请参见身份验证。

参数#

sourceLocale、targetLocales 和 data 为必填项，其余字段用于调整行为，或让调用在重复执行时更安全。

参数	类型	说明
`sourceLocale`	string	BCP-47 源语言区域（例如 `en`）。
`targetLocales`	string[]	BCP-47 目标语言区域（例如 `["de", "fr", "ja"]`）。每次请求可传 1–100 个。每个语言区域都会创建一个任务。
`data`	object	待翻译的键值内容。支持任意深度的嵌套对象和数组。
`context`	string（可选）	这份翻译 payload 的整体上下文，例如产品界面、目标受众或用途。会应用到本次请求创建的每一个任务。
`hints`	object（可选）	按 key 提供的上下文，以面包屑字符串数组表示，用于消除简短或复用字符串的歧义。
`callbackUrl`	string（可选）	此任务组的 HTTPS webhook URL。会覆盖组织默认值。不接受 HTTP。
`idempotencyKey`	string（可选）	客户端生成的键。用相同的键发送两次相同请求时，返回的是现有任务组，而不是新建一个。按引擎划分作用域。
`engineId`	string（可选）	用于执行这些任务的本地化引擎。若省略，则回退到组织的默认引擎。
`pipelineConfig`	object（可选）	按请求设置的 pipeline 覆盖项。未指定的阶段会继承引擎配置。
`lockedKeys`	string[]（可选）	值会被排除在翻译之外、并原样合并回 `outputData` 的 key 或 glob 模式。最多 100 个模式。参见锁定不可翻译的键。

请求#

json

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

必须使用 HTTPS

callbackUrl 必须使用 HTTPS。HTTP URL 会被拒绝，并返回 400 错误。

响应（202 Accepted）#

调用会立即返回，不会等待翻译完成——它会先把组 ID 和各语言区域的任务 ID 返回给你，随后平台会在后台独立处理每个任务。

json

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

字段	说明
`groupId`	整个任务组的标识符，带有 `ljg_` 前缀。请保存它——后续跟踪和查看实时进度都要靠它。
`status`	任务组创建时的状态，通常为 `pending`。
`jobs`	每个目标语言区域对应一条记录：`id`（带有 `ljb_` 前缀）、`targetLocale`，以及该任务的 `status`。
`createdAt`	ISO 8601 时间戳。

示例#

下面分别展示 Node 和 Python 的同一请求。两者都只发送一次 POST，并直接从 202 中读取组 ID 和任务数量。

javascript

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

让调用可安全重试#

选择一个有意义的键

javascript

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

后续步骤#

锁定不可翻译的键

通过 key 和 glob 模式，让 ID、slug、资源 URL 和枚举代码不参与翻译。

配置 pipeline

按请求覆盖 pipeline 各阶段，或设置每个任务都会继承的引擎级默认值。

跟踪任务组

查看任务组和各语言区域的状态，并处理某个语言区域失败而其余语言区域成功交付的情况。