读取翻译作业
查看文档的翻译目标,等待作业完成,并下载可用的输出。
使用创建作业时返回的 id 读取作业:
http
GET /v2/localization/jobs/:id
X-API-Key: YOUR_API_KEY响应包含所有文档及其目标语言区域的信息。部分翻译目标可能已完成,而其他目标仍在运行或已失败。
作业字段 #
| 字段 | 含义 |
|---|---|
id, organizationId, engineId | 作业标识、所属组织和引擎。 |
sourceLocale | 源语言。 |
trigger | 来源,例如 api、cli、ci 或某项集成。 |
status | 带标签的作业状态,详见下文。 |
createdAt, updatedAt | ISO 格式的时间戳字符串。 |
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 后,即可下载。如果应用需要同时发布所有语言,请等待所有必需的翻译目标完成,并在自己的存储中落实这一发布规则。单个文件已完成,并不代表所有语言区域都已成功。