翻译文档

上传源文件和已有译文,启动本地化任务,再下载生成的文件。

通过文档任务翻译文件,同时保留原有格式。一个任务可包含多个文件和目标语言。API 根据每个文件实际字节内容的 SHA-256 哈希值来标识文件。

你需要准备 API 密钥、组织 ID 和引擎 ID。文件本地化指南提供了完整的 Node.js 示例。

选择格式 #

为每个文档设置 format.type:

格式类型
JSON / JSONCjson / jsonc
Markdown / MDX / Markdocmd / mdx / markdoc
HTMLhtml
TypeScript / PHPtypescript / php
YAML / 以语言区域为根节点的 YAML / OpenAPI YAMLyaml / yaml-root-key / yaml-openapi
Android / Flutter ARBandroid / flutter
Apple 字符串文件 / 复数字典 / 字符串目录xcode-strings / xcode-stringsdict / xcode-xcstrings
Gettext / XLIFF / SubRippo / xliff / srt
纯文本txt
每个语言区域各占一列的 CSV 表格csv
Java 属性properties
Payload 内容payload

格式参考介绍了文件结构和控制选项。API format.options 使用文档契约;CLI 配置则将自身的选项名称映射到该契约。例如,API 对 Markdown 使用 frontmatterFields,对组件属性使用 componentProps。JSON 键选择器使用 JSONPath。

设置格式选项 #

省略 format.options 即可使用默认值。请仅设置所选类型支持的选项:

类型选项
json, jsoncJSON 选项:键规则、范围、上下文、提示和语言区域注入。
typescript, php, yaml, yaml-root-keylockedKeys、preservedKeys、ignoredKeys(默认值为 []);可选的 keyScope 和 termScope,如提供则不能为空。
mdfrontmatterFields(默认值为 ["$.title", "$.description"]);可选的 termScope,如提供则不能为空。
mdx, markdocMarkdown 选项,另加 componentProps(默认值为 [])。
html除处理器内置的可翻译属性外,还支持 componentProps(默认值为 [])。
xcode-stringsdictlockedKeys 和 preservedKeys(默认值为 []);可选的 termScope,如提供则不能为空。
flutter, xcode-strings, xcode-xcstrings, android, yaml-openapi可选的 termScope,如提供则不能为空。
csv可选的 keyColumn,即键列的表头(默认为第一个表头单元格)。
propertieslockedKeys、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 为例:

json
{
  "type": "mdx",
  "options": {
    "frontmatterFields": ["$.title", "$.description", "$.sidebar.label"],
    "componentProps": [{ "components": ["Callout"], "props": ["title"] }]
  }
}

这会翻译所选的文档前置信息、以字面量形式指定的 Callout 标题,以及文档正文。请查阅格式参考,了解受保护的代码、表达式和重建行为。

使用制品地址创建任务 #

根据准备上传的确切字节内容计算哈希值。在 Node.js 中:

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:

json
{
  "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 工作流。