第 99 篇
如何为全球读者翻译 API 文档
API7.ai
2026年07月21日
要点
- 先做国际化,再翻译。 将不随语言变化的契约数据、可翻译说明、依地区调整的呈现方式和导航分开,避免每次更新都靠人工重建。
- 保护技术标识。 即使周围的说明换了语言,路径、字段名、代码、命令、配置键、枚举值、产品名称和 URL 通常也必须保持原样。
- 统一维护术语。 术语表、翻译记忆库、风格指南和禁止翻译清单,能帮助人工翻译和机器辅助翻译保持一致。
- 逐份跟踪译文与源文的对应关系。 每个翻译页面都需要记录源文版本、目标语言与地区、状态、负责人和时效信息,便于发现差异。
- 像测试产品一样验证本地化结果。 除了语言是否通顺,还要检查链接、锚点、代码、语言标签、布局、搜索、无障碍和技术含义。
API 文档翻译是一项持续的技术发布工作。一个端点改名,就可能牵动正文、OpenAPI 描述、代码示例、导航、搜索同义词、截图,以及多个语言版本的仓库。
可靠的目标是功能一致:每种受支持语言的读者,都能依照技术上等效、及时且自然的指引完成同一项任务。无需逐句对应。
区分国际化、本地化和翻译
国际化是让文档系统能够支持不同的语言、文字、书写方向、格式和区域设置。本地化是针对特定受众调整内容。翻译负责转换语言,是本地化的一部分。
这一区分会直接影响维护成本。如果 URL 硬编码在英文句子里、截图中的标签无法替换、代码和正文混在一起,译者就只能手动修复结构。完成国际化的源文会清楚标出哪些内容可以翻译:从源文中提取可译内容并保护代码和标识符,再借助术语表和翻译记忆库完成翻译和技术审阅。构建本地化页面后,经过自动检查和视觉检查再发布,并持续监控时效。
1flowchart LR
2 S["Canonical source"] --> X["Extract translatable units"]
3 S --> P["Protect code and identifiers"]
4 X --> T["Terminology and translation memory"]
5 P --> T
6 T --> H["Human translation and technical review"]
7 H --> B["Localized build"]
8 B --> Q["Automated and visual QA"]
9 Q --> U["Publish locale"]
10 U --> M["Freshness monitoring"]
11 M --> S
12
13 classDef source fill:#e8f3ff,stroke:#1677ff,color:#102a43;
14 classDef work fill:#fff7e6,stroke:#d48806,color:#5c3b00;
15 classDef done fill:#f6ffed,stroke:#389e0d,color:#173b0b;
16 class S,X,P source;
17 class T,H,B,Q,M work;
18 class U done;按用户需求、市场重点、支持能力和质量维护成本选择要提供的语言版本。与其发布十个很快过时的版本,不如把两个版本维护好。明确每种语言覆盖整个门户、一段重点流程,还是仅覆盖参考文档中的说明,并向用户展示覆盖范围。
为翻译写好源文
清晰的源文既有利于原语言读者,也有利于翻译。Google 的全球读者写作指南建议采用常见句式、统一术语,并让列表各项的结构保持一致。这些做法可以降低人工翻译和机器辅助翻译遇到的歧义。
建议采用:
- 主语明确的短句;
- 每个有序步骤只写一项操作;
- 为同一概念使用同一个名称;
- 用表达具体动作的动词;
- 不依赖特定文化背景的示例;
- 在日期容易产生歧义的技术场景中,采用 ISO 风格的日期格式;
- 为缩写和领域术语提供定义。
避免需要额外解释的笑话、习语、体育比喻和由片段拼接的字符串。“圆满完成迁移”比用体育比喻更清楚。"Created " + count + " orders" 这样的界面字符串到了另一种语言里可能无法正确调整语序;应使用支持完整消息和复数规则的本地化系统。
不要为了方便翻译而削弱技术含义。译者需要精确的源文、上下文和术语,含糊的表述反而更难翻译。
确定哪些内容可以翻译
API 文档里改动一个字符就可能导致请求失败。应制定明确的技术标识保护规则。
以下内容通常应原样保留:
- 路径,例如
/v2/orders/{order_id}; - 方法,例如
GET和POST; - JSON 属性名和枚举值;
- 请求头、查询参数和媒体类型;
- 命令名、选项、环境变量和配置键;
- 包名、类名、函数名和导入路径;
- 代码,除非需要本地化的注释会单独维护和测试;
- URL 和片段标识符,除非目标语言有明确的对应路径;
- 商标和产品名,按品牌规范处理。
可翻译的内容包括面向读者的说明、标题、导航标签、题注、替代文本、可安全修改的注释,以及实际 API 支持本地化的消息示例。
来看下面的响应:
1{
2 "type": "https://developer.example.com/problems/validation-error",
3 "title": "The request contains invalid values.",
4 "status": 422,
5 "errors": [
6 {
7 "pointer": "/customer/email",
8 "code": "format",
9 "detail": "Enter a valid email address."
10 }
11 ]
12}只有实际 API 会返回本地化的错误文本,才能在对应语言的示例中翻译 title 和 detail 的值。字段名和数字状态码保持稳定,type 是问题类型的主要标识;本例的 errors、pointer 和 code 属于扩展,其中 pointer、code 的值也应按该 API 的约定保留。若 API 始终返回英文消息,就保留真实输出,只翻译示例周围的解释。
维护一份工具可检查的禁止翻译清单。通过标记或结构化字段明确哪些内容受保护,避免让译者逐项猜测。代码块和行内代码应在整个翻译流程中保持受保护状态。
管理术语与上下文
术语表不应只有源词和译词。还应记录:
- 定义和领域上下文;
- 各语言版本的核准译法;
- 禁用或已弃用的译法;
- 词性和大小写要求;
- 它是代码标识符、界面标签、概念还是产品名称;
- 示例句;
- 负责人和决策记录。
“route”“consumer”“tenant”和“upstream”“scope”等词在日常语言和技术语境中含义不同。翻译取决于上下文。缺乏语境的字符串可以配截图或界面参考,但截图不应成为唯一依据。
翻译记忆库可复用已审定的片段,提高一致性并减少重复工作。它也可能把旧错误或不适用的语境带到新页面。影响较大的匹配要人工复查,术语变更时及时更新记忆库。
机器翻译可以加速初稿,尤其适合重复度高的参考说明。涉及安全指引、法律承诺、破坏性操作、复杂架构或有歧义的技术术语时,应按风险安排语言审阅和技术审阅。
设计本地化 URL 和语言元数据
给每个本地化页面分配稳定的 URL,例如:
1/en/docs/orders/create
2/zh/docs/orders/create
3/ja/docs/orders/create
不要只依赖 Cookie 或浏览器状态,读者必须能分享某个确切的语言版本。切换语言时应尽量保留同一页面;若没有对应译文,明确提示,避免默默跳到无关首页。
使用有效的 BCP 47 语言标签。W3C 语言标签指南解释了 en-GB、es-419 和 zh-Hant-HK 等标签。在 HTML 中,为页面及切换语言的段落设置 lang,以支持屏幕阅读器、字体、搜索和其他依赖语言的处理。
使用 hreflang 让搜索引擎识别对应的本地化页面,并让真正翻译后的页面使用指向自身的 canonical URL。不要把所有译文都指向英文 canonical,否则可能让搜索引擎把译文视为重复内容。站点地图、导航和搜索索引也应识别语言和地区。
如果 API 本身会对面向读者的响应内容做本地化,应记录 Accept-Language、回退行为和 Content-Language。RFC 9457 允许对 Problem Details 中面向读者的成员做本地化,供程序识别的标识符则应保持稳定。
保持译文与源文一致
给每个源页面分配独立于文件名的稳定内容 ID。每份译文应记录:
- 源内容 ID 和源文修订版本或提交;
- 源语言与地区、目标语言与地区;
- 翻译状态;
- 译者和技术审阅人;
- 最近核验日期;
- 有意偏离源文的地方及其理由。
源文修改时,先区分变更的性质。只改标点,可能无需调整现有译文。若修改了限制、权限、错误行为或操作步骤,则需要尽快重新做技术审阅。涉及安全的译文一旦过时,应显示提示,或暂时提供最新源文,避免把旧指引当作现行规则展示。
1stateDiagram-v2
2 [*] --> Current
3 Current --> NeedsReview: Source text changed
4 NeedsReview --> Current: Translation updated and approved
5 NeedsReview --> Blocked: Technical meaning unclear
6 Blocked --> NeedsReview: Source owner clarifies
7 Current --> Stale: Deadline exceeded
8 Stale --> Current: Revalidated
9 Stale --> Hidden: Safety or contract risk
10 Hidden --> Current: Corrected and republished当前译文遇到源文变更后转为待审;更新并获批准后恢复为当前版本。若技术含义不明确,则先标为阻塞,等源文负责人澄清后继续审阅。超过期限的当前译文标为过时,复核通过后恢复;若存在安全或契约风险,可暂时隐藏,修正并重新发布后恢复。
用仪表板按语言与地区、内容类型、风险和负责人展示覆盖范围及文档时效。译文的总页数不够说明质量:一篇及时更新的快速入门,可能比数百个过时且访问量低的页面更重要。
对于有版本的 API,应分别跟踪语言版本和 API 版本。不能因为标题相同,就拿日文 v1 页面充当日文 v2 页面。将本地化流程与如何维护多个 API 版本的文档中介绍的多版本管理衔接起来。
测试本地化文档
自动检查应对比源文和译文的受保护标识与结构,至少验证:
- frontmatter 和语言、地区元数据;
- 标题、列表、表格、说明和代码块数量;
- 代码、JSON 键、路径、方法、命令选项和配置键;
- 内外部链接、锚点、图片和下载项;
- Mermaid 语法和节点含义;
- OpenAPI 引用及嵌入的示例;
- 语言标签、
hreflang、canonical 链接和站点地图条目; - 是否存在缺失、重复或未翻译的片段。
目标语言需要调整句子或段落顺序时,不必强求结构一模一样。检查的作用是提示哪些差异需要审阅。
视觉测试可发现内容溢出、按钮截断、表格错位、字体不合适及从右到左的排版问题。还要测试键盘操作顺序和屏幕阅读器发音。WCAG 要求程序能够识别页面语言及其中的语言切换。
技术审阅人应运行操作流程和代码示例。译文即使读起来很顺,也可能写错路由或把警告说反。应在沙盒中验证每种语言版本,采用相同的成功标准。
本地化完整的用户旅程
只有落地页翻译成当地语言,而认证报错和支持表单仍是英文,用户旅程就没有完成本地化。盘点从发现产品、注册、创建凭据,到查阅参考、使用交互式控制台和 SDK,再到访问状态页、获取支持和查看弃用通知的各个环节。
优先打通首次成功请求的路径,再处理最容易卡住用户的错误。开发者门户的语言选择应保持一致,并允许读者自由切换。许多开发者希望读本地化说明、看英文代码,也可能频繁切换。
API 管理平台可以集中维护各语言门户背后的运行时契约和策略。无论流量经过 Apache APISIX 还是其他网关,本地化文档都必须准确反映公开路由、认证方式、限制和错误行为。不要翻译网关配置标识,也不要编造 API 并未提供的本地化路径。
全球 API 文档检查清单
- 源文是否清楚、一致,便于翻译?
- 代码和技术标识符是否受到自动保护?
- 每种语言是否采用核准术语和禁止翻译清单?
- 本地化 URL 是否稳定、可分享,语言标签是否正确?
- 切换语言时,读者能否保留页面和 API 版本上下文?
- 每份译文是否记录源文版本和审阅状态?
- 技术、语言、无障碍、链接和视觉检查是否完成?
- 本地化示例是否符合 API 实际的语言行为?
- 高风险内容过时后,能否迅速提示、隐藏或修正?
- 组织有能力持续维护每个已发布的语言版本吗?
总结
要让全球读者都能信任 API 文档,需要把本地化纳入内容架构和发布流程。清晰的源文、受保护的标识符、统一维护的术语、精确到修订版本的一致性跟踪,以及分层质量检查,能让团队扩展语言覆盖范围,同时保持技术准确。
最后一篇介绍如何检验这些工作是否有效。阅读如何衡量 API 文档的成效,了解如何评估文档发现、任务完成、集成成功和内容时效。