翻译作业

创建并启动作业,处理一个或多个文档及目标语言。

每个作业通过一个本地化引擎翻译文档。每个文档都有固定的键,并为每种请求的语言设置一个翻译目标。内存中的内容使用 内联 JSON,文件则使用 产物地址。

以下所有路由均使用 https://api.lingo.dev 和 API 身份验证。

创建作业 #

http
POST /v2/organizations/:orgId/localization/jobs
Content-Type: application/json
X-API-Key: YOUR_API_KEY
Idempotency-Key: order-confirmation-v3-de-fr
json
{
  "engineId": "YOUR_ENGINE_ID",
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "documents": [
    {
      "key": "order-confirmation.json",
      "format": { "type": "json" },
      "source": { "content": { "subject": "Your order is confirmed" } }
    }
  ]
}

请求字段 #

字段必填说明
engineId是组织内调用方可用于翻译的引擎。
sourceLocale是源语言。
targetLocales是非空的目标语言区域数组,各项不得重复。文档不能将自身的源语言区域设为目标。
documents是非空的文档数组,各文档的 key 值不得重复。
originId否用于标识文档所在位置的非空标识符,最多 512 个字符,例如 github:acme/web。它将该来源的后续编辑与翻译测量关联起来。

每个文档包含以下字段:

字段必填说明
key是非空的逻辑文件路径或名称,在当前作业内必须唯一。请在不同修订版本中保持不变。
format是格式对象,包含 type 和该格式专用的 options。
source是SHA-256 产物地址;使用内联 JSON 时则为 { "content": { ... } }。
previousSource否上一版本的源产物地址。首次翻译时,请省略此字段或使用 null。
previousTranslations否{ "locale": "de", "artifact": "SHA256" } 数组,默认为 []。各语言区域不得重复,且必须属于此文档的目标语言区域。
targetLocales否用于覆盖此文档目标语言区域的非空设置,各项不得重复。省略此字段或使用 null 时,将采用作业的目标语言区域。

使用 keyScope 或 termScope 时,请为每个目标提供上一版本的译文。参见文档格式与更新。

幂等性 #

发送非空的 Idempotency-Key,长度不超过 255 个字符。键的作用域限于引擎;content-sync: 为保留前缀。请将键与原始请求一同保存。如果无法确定创建请求的响应结果,请原样重试该请求。

重复使用同一个键会返回最初用该键创建的作业,不会更新其文档或语言区域。工作内容有变化时,请使用新键。运行选项冲突可能导致 LocalizationJobIdempotencyKeyReused(422)。

创建响应 #

创建成功后,会返回 HTTP 200 和作业响应,通常带有 status: { "_tag": "Pending" }。继续操作前,请持久化保存 id。uploads 数组以 { "address": "...", "uploadUrl": "..." } 的形式列出缺失的输入产物。

创建操作会存储内联源内容,但不会启动翻译,即使 uploads 为空也不例外。

上传并启动 #

通过经过身份验证的 PUT,将每个缺失的产物上传到对应的 uploadUrl,请求中须包含原始字节。然后调用:

http
POST /v2/localization/jobs/:id/start
X-API-Key: YOUR_API_KEY

启动请求不包含请求体。其 HTTP 200 响应返回当前作业记录。对同一作业重复调用启动操作是安全的,也可用于恢复结果不确定的调度;这不会创建新作业,也不会重新运行已完成的作业。

启动时会检查已上传的产物、引擎配置和账户限制。ArtifactsNotUploaded(409)会列出缺失的输入。达到每日令牌上限(429)或额度不足时,作业会保持待处理状态;请解决问题后再启动。参见错误。

配置流水线阶段 #

启动前,请配置引擎的流水线。启动时会保存配置快照。作业最终的目标阶段会显示根据套餐可用性实际选定的工作。

收集结果与故障恢复 #

获取作业,查看每个目标并下载已完成的文件。通过阶段进度区分模型处理、等待审核、已跳过的工作和失败情况。

失败的作业仍可能包含已完成的目标。请保留这些输出,解决失败原因后,再使用新的幂等键,仅提交需要重新生成的工作。请将源内容的修订版本与作业 ID 一同保存,避免后续交付覆盖较新的译文。

列出作业,按引擎、状态、触发方式或服务密钥查找提交记录。