构建翻译 API 工作流
在服务器端翻译应用记录,并让已接受的各语言版本始终关联到对应的源文修订版本。
编辑更新产品描述后,每个译文版本都需要同步反映这一变化。API 响应提供新文本;你的应用则负责判断文本属于哪条记录、源文是否仍是当前版本,以及何时向读者展示。
本指南将首次翻译请求扩展为可重复执行的后端工作流,适用于由你的应用管理的产品描述、帮助条目等记录。静态应用资源通常更适合采用 CI 文件工作流,因为现有的资源编译和代码仓库审核流程已经提供了验证环节。
发送完整连贯的内容 #
用一个内联 JSON 文档为一条产品记录创建本地化任务。将相关字段放在一起,便于通过上下文说明它们的用途;同时保持键名稳定,让下载的对象能够映射回原来的字段。
将以下请求体提交到 POST /v2/organizations/:orgId/localization/jobs,并提供 API 密钥以及此修订版本的稳定 Idempotency-Key:
{
"engineId": "YOUR_ENGINE_ID",
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"documents": [
{
"key": "products/bottle.json",
"format": {
"type": "json",
"options": {
"context": "Product listing for a reusable drinks bottle",
"hints": {
"$.title": ["Catalog card title"],
"$.description": ["Short product description; do not add specifications"]
}
}
},
"source": {
"content": {
"title": "Insulated bottle",
"description": "Keeps drinks cold during your commute."
}
}
}
]
}将凭据保存在后端,并明确指定引擎。通过共享术语表统一产品术语的翻译,通过文档上下文说明本次使用场景。JSON 参考介绍了提示和受保护路径。
在后台执行翻译 #
启动任务前,先保存返回的任务 ID。上传 uploads 中列出的所有内容,再调用 POST /v2/localization/jobs/:id/start。即使使用内联 JSON,也必须显式启动任务。
由后端工作进程轮询任务,并通过返回的 URL 下载已完成的目标文件。应用将这项工作持久化并加入队列后,就可以返回编辑发起的保存请求,无需在翻译或人工审核期间一直保持请求连接。
进行增量更新时,请保留先前的源文文件和已接受的目标文件,并在下一次文档请求中一并提供。文档更新说明了哪些内容可以复用。
源文保存后再创建工作记录 #
源文事务提交后,在自己的存储系统中创建一条工作记录,包含内容 ID、源文修订版本、目标语言区域、本地化引擎/配置记录和处理状态,再根据这条记录将翻译加入队列。这样可以避免工作进程翻译之后被源文事务回滚的编辑内容。
为每种目标语言单独记录结果。德语可能已经就绪,法语却可能还需要重试或审核。如果只用一个总体的“已翻译”标记,应用在决定提供哪些内容时就无法识别这种差异。你添加的任何状态名称都属于应用自身的设计,并非 API 响应中定义的状态用语。
仅接受对应预期修订版本的输出 #
源文编辑与翻译完成的顺序可能不一致。例如:
| 事件 | 应用操作 |
|---|---|
| 修订版本 12 已保存 | 将修订版本 12 的德语翻译加入队列。 |
| 该任务尚未完成,修订版本 13 已保存 | 将修订版本 13 加入队列,并标记为当前源文。 |
| 修订版本 13 的翻译完成 | 验证并接受译文,将其关联到修订版本 13。 |
| 修订版本 12 的翻译随后完成 | 保留其已记录的结果,不替换修订版本 13 已接受的文本。 |
启用译文时,将工作记录中的源文修订版本与当前源文修订版本进行比较。在存储系统中执行比较和写入时,都以该修订版本为条件,避免两次操作之间发生未被察觉的源文编辑。如果当前版本的工作尚未加入队列或已经失败,请安排当前修订版本的翻译,不要将旧结果重新标记为当前版本。
读取时,获取所请求语言和修订版本对应的已接受译文。你需要决定缺少译文时应用如何处理:显示源文、使用指定的回退语言、提供已明确跟踪的旧译文,或暂缓发布。如何选择,取决于过时或未翻译的文本可能给读者带来什么影响。结账条件的变更可能需要比普通产品描述更严格的处理策略。
通过远端标识和本地记录恢复工作 #
发送提交请求前,先持久化保存幂等键;创建请求返回后,立即保存任务 ID。发生网络超时后,使用同一个键重发内容不变的创建请求,或获取已记录的任务。重复执行启动操作仍会作用于同一个任务。
遇到临时读取失败时,采用退避策略继续轮询。客户端达到等待时限,只会停止等待,不会终止服务器上的工作。分别保留已完成的目标输出和失败目标的详细信息;即使任务失败,也可能包含可用的已完成文件。
身份验证错误、引擎被禁用、输入无效和账户限额问题都需要先解决。准入限制解除后,可以再次启动待处理任务。对于执行过程中失败的工作,请修正导致失败的问题,再使用新的幂等键提交受影响的文档/语言区域。
接受结果时,对每个结果执行相同的修订版本检查,包括恢复后获取的结果。下载完成仅表示文本已可用;是否可以发布,仍由你的验证和审核策略决定。
测试记录的生命周期 #
使用一条包含变量的简短记录,依次测试源文更新、某个语言区域失败,以及翻译完成顺序不一致的情况。除了文本本身,还要检查存储的字段键名和语言标识。应用应只提供符合你的接受策略的版本,审核者也应能将其追溯到对应的源文。
衡量质量时,请保留配对的源文和译文,以及用于检查它们的标准。测量设计可独立于生成工作流应用。这样,记录就能区分返回的文本、测量得出的答案、人工接受和发布,而不会将它们视为同一个事件。