读取翻译作业

查看文档的翻译目标,等待作业完成,并下载可用的输出。

使用创建作业时返回的 id 读取作业:

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

响应包含所有文档及其目标语言区域的信息。部分翻译目标可能已完成,而其他目标仍在运行或已失败。

作业字段 #

字段含义
id, organizationId, engineId作业标识、所属组织和引擎。
sourceLocale源语言。
trigger来源,例如 api、cli、ci 或某项集成。
status带标签的作业状态,详见下文。
createdAt, updatedAtISO 格式的时间戳字符串。
createdBy创建者信息;无法获取时为 null。使用个人密钥创建的作业归属于该密钥对应的用户。
documents文档及其格式、源地址,以及翻译目标的进度。
uploads作业处于待处理状态时,列出缺失的产物地址及上传 URL;作业开始后为空。

作业状态 #

status._tag应采取的操作
Pending上传缺失的产物并调用 /start。
Running稍后再次轮询;查看翻译目标的各阶段,确认是否正在处理或等待审核。
Completed下载并检查输出。验收时也需检查各阶段的警告。
Failed读取 status.message 和翻译目标的失败信息。已完成的目标仍然可用。
Cancelled处理已停止。检查翻译目标,查看是否已有完成的输出。

Completed、Failed 和 Cancelled 是作业的终态。部分失败指作业已失败,其中部分翻译目标已完成,部分已失败。

文档和翻译目标字段 #

每个文档包含 id、key、format、source、previousSource 和 targets。即使请求中提供的是内联 JSON,source 仍为产物地址。previousSource 缺失时为 null。

每个翻译目标包含:

字段含义
locale目标语言。
previousTranslation先前的目标产物地址,或 null。
status其 _tag 字段的值为 Pending、Completed 或 Failed。
stages阶段进度,包括状态和单元数量。

已完成的翻译目标,其状态包含 artifact 和 downloadUrl;失败的翻译目标,其状态包含 message。以下响应片段展示了一个已完成的翻译目标的状态:

json
{
  "_tag": "Completed",
  "artifact": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "downloadUrl": "/v2/localization/jobs/lfr_example/artifacts/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

请使用实际返回的地址和 URL。该 URL 是相对于 https://api.lingo.dev 的地址,访问时需要身份验证,并非公开的签名下载链接。下载返回的是文档对应格式的文件字节。

多个翻译目标可以共用一个产物。Apple 字符串目录会将请求的语言合并到一个 .xcstrings 文件中;只需保存一次合并后的输出,并检查其中的语言区域条目,不要将每次下载都视为独立的单语言目录。

轮询和收集 #

按限定的时间间隔轮询作业,例如每两秒一次,并在应用中设置截止时间。如果读取暂时失败,请保留 ID,并采用退避策略重试。结束等待不会取消服务器端的处理。人工审核所需的时间可能远超应用请求较短的超时时限。

翻译目标的状态变为 Completed 后,即可下载。如果应用需要同时发布所有语言,请等待所有必需的翻译目标完成,并在自己的存储中落实这一发布规则。单个文件已完成,并不代表所有语言区域都已成功。

如需完整的轮询和下载程序,请参阅快速入门。有关源内容修订的处理和重试决策,请参阅构建翻译工作流。