翻译文档
上传源文件和已有译文,启动本地化任务,再下载生成的文件。
通过文档任务翻译文件,同时保留原有格式。一个任务可包含多个文件和目标语言。API 根据每个文件实际字节内容的 SHA-256 哈希值来标识文件。
你需要准备 API 密钥、组织 ID 和引擎 ID。文件本地化指南提供了完整的 Node.js 示例。
选择格式 #
为每个文档设置 format.type:
| 格式 | 类型 |
|---|---|
| JSON / JSONC | json / jsonc |
| Markdown / MDX / Markdoc | md / mdx / markdoc |
| HTML | html |
| TypeScript / PHP | typescript / php |
| YAML / 以语言区域为根节点的 YAML / OpenAPI YAML | yaml / yaml-root-key / yaml-openapi |
| Android / Flutter ARB | android / flutter |
| Apple 字符串文件 / 复数字典 / 字符串目录 | xcode-strings / xcode-stringsdict / xcode-xcstrings |
| Gettext / XLIFF / SubRip | po / xliff / srt |
| 纯文本 | txt |
| 每个语言区域各占一列的 CSV 表格 | csv |
| Java 属性 | properties |
| Payload 内容 | payload |
格式参考介绍了文件结构和控制选项。API format.options 使用文档契约;CLI 配置则将自身的选项名称映射到该契约。例如,API 对 Markdown 使用 frontmatterFields,对组件属性使用 componentProps。JSON 键选择器使用 JSONPath。
设置格式选项 #
省略 format.options 即可使用默认值。请仅设置所选类型支持的选项:
| 类型 | 选项 |
|---|---|
json, jsonc | JSON 选项:键规则、范围、上下文、提示和语言区域注入。 |
typescript, php, yaml, yaml-root-key | lockedKeys、preservedKeys、ignoredKeys(默认值为 []);可选的 keyScope 和 termScope,如提供则不能为空。 |
md | frontmatterFields(默认值为 ["$.title", "$.description"]);可选的 termScope,如提供则不能为空。 |
mdx, markdoc | Markdown 选项,另加 componentProps(默认值为 [])。 |
html | 除处理器内置的可翻译属性外,还支持 componentProps(默认值为 [])。 |
xcode-stringsdict | lockedKeys 和 preservedKeys(默认值为 []);可选的 termScope,如提供则不能为空。 |
flutter, xcode-strings, xcode-xcstrings, android, yaml-openapi | 可选的 termScope,如提供则不能为空。 |
csv | 可选的 keyColumn,即键列的表头(默认为第一个表头单元格)。 |
properties | lockedKeys、preservedKeys、ignoredKeys(默认为 [])以及可选的非空 keyScope,按旧式模式匹配完整键名;若模式以 $ 开头,则按 JSONPath 匹配;可选的非空 termScope;lockedPatterns(默认为 []),使用 RE2 正则表达式匹配值中保留原文、不作翻译的内容。 |
payload, po, xliff, srt, txt | 无额外选项。 |
键规则、键范围和文档前置信息字段均使用 JSONPath 查询。termScope 按区分大小写的子串进行匹配,选中包含任一所提供词语的完整源内容单元;"cat" 可以匹配 "catalog"。当某种格式同时支持 keyScope 和 termScope 时,同时提供两者会选中它们的交集。两种范围都需要已有译文作为合并目标。选择和复用行为因格式而异,详见增量更新。这些 API 选项与 CLI 的 --key 格式支持不同。
组件属性规则包含 props(非空的属性名称数组),还可包含 components(非空数组,用于将规则限定到指定名称的组件)。省略 components 时,规则适用于任意组件。以 MDX 为例:
{
"type": "mdx",
"options": {
"frontmatterFields": ["$.title", "$.description", "$.sidebar.label"],
"componentProps": [{ "components": ["Callout"], "props": ["title"] }]
}
}这会翻译所选的文档前置信息、以字面量形式指定的 Callout 标题,以及文档正文。请查阅格式参考,了解受保护的代码、表达式和重建行为。
使用制品地址创建任务 #
根据准备上传的确切字节内容计算哈希值。在 Node.js 中:
import { createHash } from "node:crypto";
import { readFile } from "node:fs/promises";
const bytes = await readFile("messages/en.json");
const address = createHash("sha256").update(bytes).digest("hex");创建任务,并将生成的地址设为文档的 source:
{
"engineId": "YOUR_ENGINE_ID",
"sourceLocale": "en",
"targetLocales": ["de"],
"documents": [
{
"key": "messages/en.json",
"format": { "type": "json" },
"source": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
]
}将示例地址替换为计算出的哈希值,并保存返回的任务 ID。uploads 会列出存储中缺失的输入制品;已存储的内容无需重复上传。
上传字节并启动任务 #
针对每个 uploads 条目,向其 uploadUrl 发送经过身份验证的 PUT 请求,附带 Content-Type: application/octet-stream,并以原始字节作为请求体。启动任务前,请上传源文件及所有引用的先前文件。
每个制品的大小上限为 25 MiB。哈希值不匹配时返回 ArtifactChecksumMismatch;文件超出大小限制时返回 RequestBodyTooLarge。如果计算文本的哈希值后,又在上传前更改换行符,字节内容就会发生变化,导致验证失败。
所有文件上传成功后,调用 POST /v2/localization/jobs/:id/start。制品只能在任务启动前上传。查看任务的目标进度,再通过返回的 URL 下载已完成的文件。
更新现有文档 #
增量更新需要保留三类输入:新源文件、先前的源文件,以及每个目标语言区域的当前译文。请提供:
source:新源文件的制品地址。previousSource:上一修订版本使用的源文件地址。previousTranslations:每份可用译文对应一个{ "locale": "de", "artifact": "..." }条目。
提供先前目标文件的字节内容时,请确保其中包含本地人工修改。格式处理器可以复用未更改的内容,并翻译已更改的内容。对于普通 JSON,如果省略先前的源文件,就无法复用源内容未更改的部分。其他格式可以按各自的合并规则采用现有目标内容。如果需要区分源内容的修改与未更改的消息,请保留完整基线。
通过 keyScope 或 termScope 发起限定范围的请求时,每个目标语言区域都必须有先前的译文。JSON、JSONC、TypeScript 和 PHP 会重新生成所选字符串,包括源值未更改的字符串,并将其合并到现有目标内容中。提供先前的源文件后,YAML、以语言区域为根节点的 YAML 和 OpenAPI YAML 可以复用所选内容中未更改的部分。即使没有先前的源文件,XCStrings 也可以复用嵌入或提供的目标值。因此,选中的单元并不一定需要重新翻译。
请求重新生成前,请先向引擎提供所需的术语或规则,并在生成后检查目标内容。如果需要将措辞精确修改为某种表述,直接编辑目标内容即可避免依赖重新生成来获得特定措辞。
创建后续任务前,请通过 PUT /v2/organizations/:orgId/localization/artifacts/:address 存储基线。请求需经过身份验证,并以文件字节作为请求体。此路由要求你拥有组织内某个引擎的翻译访问权限,并会返回制品元数据。同样适用 25 MiB 大小限制和哈希检查。
请先将结果下载到临时文件。替换应用文件前,将结果与提交的源文件修订版本进行比较,同时核对提交后对目标内容所做的修改。保留已审核的译文介绍了相应的 CLI 工作流。