网站本地化

OTel 网站使用 Hugo 的 multilingual framework 来支持页面的本地化。 英语是默认语言，而美式英语是默认的本地化语言形式。 随着其他语言的本地化的增加，你可以从顶部导航栏中的语言下拉菜单中看到这些语言。

翻译指南

当翻译英文网站页面时，我们建议你遵循本部分中提供的指南。

概要

✅ 应做事项

❌ 不应做事项

标题 ID

为确保标题的锚点目标在各种本地化版本中保持一致，在翻译标题时：

• 如果标题有显式的 ID，那么请保留该标题的显式 ID。 标题 Heading ID 语法是使用类似 { #some-id } 这样的语法，写在标题文本之后。
• 否则，需明确声明一个与原始英文标题的自动生成 ID 相对应的标题 ID。

链接

请勿翻译链接引用。这同样适用于外部链接、网站页面的路径以及诸如图片之类的局部资源路径。

唯一的例外是指向外部页面的链接 (像这样的链接 https://en.wikipedia.org) 即那些拥有针对你所在地区的特定版本的外部页面的链接。 通常情况下，这意味着要将 URL 中的 en 替换为你所在地区的语言代码。

链接定义标签

请不要翻译 Markdown 链接定义中的标签。 应将标签重写为翻译后的链接文本。例如，考虑以下 Markdown 内容：

[Hello], world! Welcome to the [OTel website][].

[hello]: https://code.org/helloworld
[OTel website]: https://opentelemetry.io

以上 Markdown 将被翻译为法语：

[Bonjour][hello], le monde! Bienvenue sur le [site OTel][OTel website].

[hello]: https://code.org/helloworld
[OTel website]: https://opentelemetry.io

图片和图表

除非你要对图像本身的文本进行本地化处理，否则请勿复制图像文件²。

务必对 Mermaid 图表中的文本进行翻译。

Include 文件

你需要像翻译其他页面内容一样，对 _includes 目录下的页面片段进行翻译。

短代码

一些基础短代码包含你可能需要进行本地化处理的英文文本 – 尤其是那些包含在 layouts/_shortcodes/docs 中的短代码，这种情况更为明显。 如果你需要创建某个短代码的本地化版本，可将其放置在 layouts/_shortcodes/xx 目录下， 其中 xx 是你所在地区的语言代码。之后，使用与原始基础短代码相同的相对路径。

跟踪本地化页面的差异

维护本地化页面的主要挑战之一，是识别对应的英文页面何时进行了更新。本节将解释我们是如何处理这个问题的。

前端元数据字段 default_lang_commit

当编写一个本地化页面时，例如 content/zh/<some-path>/page.md，这个翻译版本是基于 content/en/<some-path>/page.md 对应英文页面在特定的main 分支 commit 版本。在这个代码仓库中，每个本地化页面都会在其前端元数据里 按以下方式标识出对应的英文页面的提交信息：

---
title: Your localized page title
# ...
default_lang_commit: <most-recent-commit-hash-of-default-language-page>
---

上述前端元数据会位于 content/zh/<some-path>/page.md 文件中。 提交哈希值将与 content/en/<some-path>/page.md 文件在 main 分支上的最新提交相对应。

跟踪英文页面的变更情况

随着英文页面的更新，你可以通过运行以下命令来跟踪那些需要更新的对应本地化页面：

$ npm run check:i18n
1       1       content/en/docs/platforms/kubernetes/_index.md - content/zh/docs/platforms/kubernetes/_index.md
...

你可以通过提供如下路径的方式，将目标页面限制为一个或多个本地化版本:

npm run check:i18n -- content/zh

查看变更详情

对于任何需要更新的本地化页面，你可以通过使用 -d 标志并提供本地化页面的路径，来查看对应英文页面的差异详情； 若省略路径，则会查看所有页面的差异详情。例如：

$ npm run check:i18n -- -d content/zh/docs/platforms/kubernetes
diff --git a/content/en/docs/platforms/kubernetes/_index.md b/content/en/docs/platforms/kubernetes/_index.md
index 3592df5d..c7980653 100644
--- a/content/en/docs/platforms/kubernetes/_index.md
+++ b/content/en/docs/platforms/kubernetes/_index.md
@@ -1,7 +1,7 @@
 ---
 title: OpenTelemetry with Kubernetes
 linkTitle: Kubernetes
-weight: 11
+weight: 350
 description: Using OpenTelemetry with Kubernetes
 ---

为新页面添加 default_lang_commit

在为你的本地化版本创建页面时，请记住在页面的前端元数据中添加 default_lang_commit， 并附上 main 分支上合适的提交哈希值。

如果你的页面翻译是基于 main 分支中哈希值为 <hash> 的英文页面，那么运行以下命令， 使用该提交哈希值 <hash> 自动将 default_lang_commit 添加到你的页面文件的前端元数据中。 如果你的页面现在与 main 分支的 HEAD 版本同步，你可以指定 HEAD 作为参数。例如：

npm run check:i18n -- -n -c 1ca30b4d content/ja
npm run check:i18n -- -n -c HEAD content/zh/docs/concepts

要列出缺少哈希键的本地化页面文件，请运行：

npm run check:i18n -- -n

更新现有页面的 default_lang_commit

当你更新本地化页面以匹配对应英文页面所做的更改时，要确保同时更新 default_lang_commit 提交哈希值。

如果你已批量更新了所有存在差异的本地化页面，你可以使用 -c 标志，后面跟上一个commit hash 或者’HEAD’（表示使用main@HEAD）来更新这些文件的提交哈希值。

npm run check:i18n -- -c <hash> <新文件的路径>
npm run check:i18n -- -c HEAD <新文件的路径>

不一致状态

运行 npm run fix:i18n:status 命令，为那些与默认版本有差异的目标本地化页面添加前端元数据字段 drifted_from_default。 该字段很快会用于在相对于其英文对应页面存在差异的页面顶部显示一个banner。

脚本帮助

若要获取该脚本的更多详细信息，请运行 npm run check:i18n -- -h.

新增本地化语言

对在 OTel 网站上新增一个本地化语言感兴趣？请联系维护者表达你的兴趣，例如通过 GitHub 讨论或 Slack 的 #otel-docs-localization 频道。本节将解释如果新增一个本地化语言所需的步骤。

1. 组建本地化团队

新增一个本地化语言的核心是建立一个积极且互助的社区。要为 OpenTelemetry 网站启动一个新的本地化语言，你需要：

1. 一位熟悉目标语言的 本地化导师，例如 CNCF 术语表或 Kubernetes 网站的活跃 Approver。
2. 至少两位潜在的贡献者。

2. 启动本地化：创建一个 Issue

当你的本地化团队已经建立或正在组建时，创建一个包含以下任务列表的 Issue：

1. 查找你要添加的语言的官方 ISO 639-1 语言代码。 我们将在本节的其余部分中将此语言代码称为 LANG_ID。 如果你对使用哪个标签（尤其是子区域）有疑问，请咨询维护者。

2. 确定导师和潜在贡献者 的 GitHub 用户名。

3. 创建一个 新 Issue， 并在提交的 Issue 评论中包含以下任务列表：

   - [ ] Language info:
     - ISO 639-1 language code: `LANG_ID`
     - Language name: ADD_NAME_HERE
   - [ ] Locale team info:
     - [ ] Locale mentor: @GITHUB_HANDLE1, @GITHUB_HANDLE2, ...
     - [ ] Contributors: @GITHUB_HANDLE1, @GITHUB_HANDLE2, ...
   - [ ] Read through
         [Localization](https://opentelemetry.io/docs/contributing/localization/)
         and all other pages in the Contributing section
   - [ ] Localize site homepage (only) to YOUR_LANGUAGE_NAME and submit a PR.
         For details, see
         [Localize the homepage](https://opentelemetry.io/docs/contributing/localization/#homepage).
   - [ ] OTel maintainers:
     - [ ] Update Hugo config for `LANG_ID`
     - [ ] Configure cSpell and other tooling support
     - [ ] Create an issue label for `lang:LANG_ID`
     - [ ] Create org-level group for `LANG_ID` approvers
     - [ ] Update components owners for `content/LANG_ID`
   - [ ] Create an issue to track the localization of the **glossary**. Add the
         issue number here. For details, see
         [Localize the glossary](https://opentelemetry.io/docs/contributing/localization/#glossary).
   

3. 本地化首页

提交一个 PR，在文件 content/LANG_ID/_index.md 中添加网站首页的翻译， 且不要包含其他内容。请确保维护者有权编辑你的 PR，因为他们需要添加一些额外更改以新增本地化语言。

在你的第一个 PR 合并后，维护者将设置 Issue 标签、组织群组和组件所有者。

4. 本地化术语表

第二个需要本地化的页面是术语表。 这是面向本地化读者的一个关键页面，因为它定义了可观测性及 OpenTelemetry 中的核心术语。 尤其当你的语言中不存在这些术语时，这一点尤为重要。

参考 Ali Dowair 在 Write the Docs 2024 上的演讲主题翻译艺术：如何本地化技术内容及其演讲视频。

5. 按小步推进本地化其他页面

在术语体系确立后，你可以开始本地化网站的其他页面。

OTel 维护者清单

Hugo

为 LANG_ID 更新 Hugo 配置。为 LANG_ID 添加合适条目：

• config/_default/hugo.yaml 中的 languages
• config/_default/module-template.yaml 中的 module.mounts 至少应添加一个针对 content 的 source-target 项。 仅当该语言内容足够多时，再考虑为 en 添加回退页面条目。

拼写检查

查找是否存在作为 NPM 包发布的 cSpell 字典@cspell/dict-LANG_ID。 如果没有适合你方言或地区的字典，请选择最接近的地区版本。

如果完全没有可用字典，可以跳过本节。否则：

• 将该 NPM 包添加为开发依赖，例如： npm install --save-dev @cspell/dict-bn
• 创建 .cspell/LANG_ID-words.txt 文件，作为 LANG_ID 的站点本地词典。
• 在 .cspell.yml 中添加以下条目：
  • import
  • dictionaryDefinitions
  • dictionaries：这里应添加两个条目，一个为 LANG_ID，另一个为 LANG_ID-words.txt

其他工具支持

• Prettier 支持：如果 Prettier 对 LANG_ID 支持不佳，请在 .prettierignore 中添加忽略规则。

Approver 与维护者指南

含语义变更的 PR 不应跨语言提交

Approver 应确保对文档页面进行语义变更的 PRs 不跨多个语言版本。 语义变更是指影响页面内容含义的修改。我们的文档本地化流程确保每种语言的 Approver 会在适当的时候审查英文修改，以确定是否适用于其本地化版本，并决定如何整合。

如有需要，Approver 将通过各自语言的 PR 进行修改。

纯编辑性修改可跨语言提交

纯编辑性修改是指不影响内容含义的更新，可跨语言进行。这类修改包括：

• 链接维护：修复因页面移动或删除而导致的链接路径错误；
• 资源更新：更新已移动的外部资源链接；
• 定向内容添加：在不便更新整个文件时，为已偏移的文件添加特定新定义或段落。

链接修复与资源更新

例如，当英文文档页面移动或删除时，可能导致其他语言版本的链接检查失败。 此时，请在每个受影响页面中进行以下更新：

• 更新到新页面路径的链接引用；
• 在 front matter 中的 default_lang_commit 行末添加注释 # patched；
• 不做其他修改；
• 重新运行 npm run check:links 并确保无链接错误。

当一个外部链接指向的资源（例如 GitHub 文件）被移动但语义未改变时，可考虑：

• 从 refcache 中移除失效链接；
• 按前述方式更新所有语言版本的链接。

向已偏移文件中添加定向内容

当需要向与英文版本不完全同步的本地化文件中添加新内容时，可选择定向更新，而无需更新整个文件。 例如，当英文术语表新增 “cardinality” 词条时，你可以仅在本地化版本中添加该定义。

操作流程示例：

• 仅将 “cardinality” 定义块添加至本地化术语表文件；
• 在 front matter 中的 default_lang_commit 行末添加 # patched；
• 保留其他内容不变；
• 在 PR 描述中明确说明：
  • 添加的具体内容（例如 “cardinality” 定义）；
  • 文件中仍存在未同步内容；
  • 定向更新的理由（例如“为本地读者提供关键新术语，无需同步整个文件”）。

这种方式可实现对本地化内容的渐进改进，同时保持对同步状态的可见性。