跳转到正文
API 101
本文目录

第 99 篇

如何为全球读者翻译 API 文档

要点

  • 先做国际化,再翻译。 将不随语言变化的契约数据、可翻译说明、依地区调整的呈现方式和导航分开,避免每次更新都靠人工重建。
  • 保护技术标识。 即使周围的说明换了语言,路径、字段名、代码、命令、配置键、枚举值、产品名称和 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 文档的成效,了解如何评估文档发现、任务完成、集成成功和内容时效。

编辑本篇文章

获取方案