翻译 JSON
提交包含上下文、提示和受保护路径的 JSON 对象,再下载翻译结果。
如果应用的源内容已在内存中,可直接在本地化任务中发送 JSON 对象。Lingo.dev 会将其存储为 JSON 文档,并为每个目标语言区域生成一份输出。
快速入门提供了完整的示例程序。本参考文档介绍 JSON 专用的请求字段。
提交内联文档 #
在 POST /v2/organizations/:orgId/localization/jobs 创建任务,在 X-API-Key 中提供 API 密钥,并为本次提交设置一个保持不变的 Idempotency-Key:
{
"engineId": "YOUR_ENGINE_ID",
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"documents": [
{
"key": "settings.json",
"format": {
"type": "json",
"options": {
"context": "Settings dialog in a team collaboration application",
"hints": { "$.save": ["Button that saves the edited settings"] },
"lockedKeys": ["$.productName"]
}
},
"source": {
"content": {
"save": "Save changes",
"cancel": "Cancel",
"productName": "Acme"
}
}
}
]
}源内容必须是 JSON 对象,可包含嵌套对象和数组。字符串叶节点可供翻译;数字、布尔值和 null 值保留原有的 JSON 类型。如果字符串类型的标识符、产品名称或 URL 需要保持不变,请为其设置保护。
内联源内容使用 format.type: "json"。对于 JSONC 或其他文件格式,请上传文件的字节内容。
添加上下文并选择内容 #
将 JSON 选项放入文档的 format.options 中:
| 选项 | 作用 |
|---|---|
context | 用于描述内容用途或受众的非空文本。 |
hints | 将 JSONPath 查询映射到非空提示数组,数组中的每条提示也必须非空。选中字符串匹配到的所有提示会累积应用。默认为空对象。 |
lockedKeys | 直接复制选中的源值,不进行翻译。默认为 []。 |
preservedKeys | 优先复用上一版目标内容中选中的值;若不存在,则复制源值。默认为 []。 |
ignoredKeys | 从输出中移除选中的值。默认为 []。 |
keyScope | 重新生成非空 JSONPath 查询列表选中的字符串。每个目标语言区域都必须有上一版翻译。 |
termScope | 重新生成与非空源词语列表匹配的字符串。每个目标语言区域都必须有上一版翻译。 |
injectLocale | 将目标语言区域写入一个 JSONPath 位置,例如 $.meta.locale。该位置的子树会受到保护,不参与翻译。 |
在 API 请求中使用 JSONPath。$.title 选择根级属性;$.nav.home 选择嵌套属性;$['nav.home'] 选择字面上包含点号的键;$..productName 选择任意深度的该属性。选中对象或数组时,也会选中其下所有层级的字符串。单独的键名不是有效的 API 查询。
键控制规则会在翻译前解析。被忽略的值会被移除;锁定的源值优先于保留的目标值。范围选择不会覆盖这些控制规则。有关输出组装和 ICU 消息的说明,请参阅 JSON 格式参考。
termScope 按区分大小写的方式匹配源字符串中的子字符串。列表中的任一词语都可选中字符串:"cat" 也能匹配 "catalog",而 "login" 不会匹配 "Login"。选中的字符串会整体重新生成,而不只是重新生成匹配的词语。当 keyScope 和 termScope 同时存在时,字符串必须同时满足两者的条件。如果子字符串匹配会选中无关消息,请使用精确的 JSONPath 键选择。
启动任务并读取结果 #
保存创建任务时返回的 id。如果任务还引用了之前的文件或其他文档,请上传 uploads 中的每一项,再调用 POST /v2/localization/jobs/:id/start。
读取 GET /v2/localization/jobs/:id,并检查每个文档的 targets。带有 status._tag: "Completed" 的目标会包含 status.downloadUrl。使用相同的身份验证方式从该 URL 下载,即可获取 JSON 对象。任务响应本身仅包含进度和产物地址,不包含翻译后的对象。
更新时,请按照更新现有文档中的说明提交上一版源内容和目标内容的产物。将新的源内容版本与任务 ID 一起保存,以免延迟返回的结果覆盖较新的内容。