翻译作业
创建并启动作业,处理一个或多个文档及目标语言。
每个作业通过一个本地化引擎翻译文档。每个文档都有固定的键,并为每种请求的语言设置一个翻译目标。内存中的内容使用 内联 JSON,文件则使用 产物地址。
以下所有路由均使用 https://api.lingo.dev 和 API 身份验证。
创建作业 #
POST /v2/organizations/:orgId/localization/jobs
Content-Type: application/json
X-API-Key: YOUR_API_KEY
Idempotency-Key: order-confirmation-v3-de-fr{
"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,请求中须包含原始字节。然后调用:
POST /v2/localization/jobs/:id/start
X-API-Key: YOUR_API_KEY启动请求不包含请求体。其 HTTP 200 响应返回当前作业记录。对同一作业重复调用启动操作是安全的,也可用于恢复结果不确定的调度;这不会创建新作业,也不会重新运行已完成的作业。
启动时会检查已上传的产物、引擎配置和账户限制。ArtifactsNotUploaded(409)会列出缺失的输入。达到每日令牌上限(429)或额度不足时,作业会保持待处理状态;请解决问题后再启动。参见错误。
配置流水线阶段 #
启动前,请配置引擎的流水线。启动时会保存配置快照。作业最终的目标阶段会显示根据套餐可用性实际选定的工作。
收集结果与故障恢复 #
获取作业,查看每个目标并下载已完成的文件。通过阶段进度区分模型处理、等待审核、已跳过的工作和失败情况。
失败的作业仍可能包含已完成的目标。请保留这些输出,解决失败原因后,再使用新的幂等键,仅提交需要重新生成的工作。请将源内容的修订版本与作业 ID 一同保存,避免后续交付覆盖较新的译文。
列出作业,按引擎、状态、触发方式或服务密钥查找提交记录。