站点本地化

以非英语本地化语言创建和维护网站页面。

OTel 网站使用 Hugo 的 多语言框架 来支持页面本地化。英语是默认语言，美国英语是默认的（隐式）本地化。支持的本地化语言越来越多，如顶部导航栏的语言下拉菜单所示。

翻译指南

翻译英文网站页面时，我们建议您遵循本节提供的指南。

摘要

✅ 推荐

  • 翻译:
    • 页面内容，包括
      • Mermaid 图表文本字段
      • 代码摘录中的代码注释（可选）
    • 前端字段的 title、linkTitle 和 description 值
    • 所有页面内容和前端，除非另有说明
  • 保留原始文本的内容、含义和风格
  • 以小批量方式提交工作，通过小的拉取请求
  • 如有任何疑问或问题，请通过 Slack #otel-docs-localization 或 #otel-comms 频道联系维护者
    • Slack #otel-docs-localization 或 #otel-comms 频道
    • 讨论、问题或 PR 评论

❌ 不推荐

  • 翻译:
    • 此仓库中资源的文件名或目录名
    • 链接，包括标题 ID 1
    • 内联代码片段，例如：inline code example
    • 标记为 notranslate 的 Markdown 元素（通常作为 CSS 类），尤其是标题
    • 前端字段，但未在推荐中列出的除外。特别是，不要翻译 aliases。如有疑问，请咨询维护者。
    • Code
  • 创建图片副本，除非您本地化图片中的文本
  • 添加新的或更改
    • 与原始意图不同的内容
    • 呈现风格，包括：格式、布局和设计风格（例如，排版、字母大小写和间距）。

标题 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.org.cn

在法语中，这将翻译为

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

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

图片和图表

除非您在图片中本地化文本，否则不要复制图片文件2。

要翻译Mermaid图表中的文本。

包含文件

要翻译 _includes 目录下的页面片段，就像翻译其他页面内容一样。

短代码

一些基础短代码包含英文文本，您可能需要对其进行本地化——这尤其适用于包含在layouts/_shortcodes/docs中的短代码。

如果您需要创建短代码的本地化版本，请将其放在 layouts/_shortcodes/xx 下，其中 xx 是您本地化的语言代码。然后，使用与原始基础短代码相同的相对路径。

跟踪本地化页面的偏差

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

default_lang_commit 前端字段

编写本地化页面时，例如 content/<some-path>/page.md，此翻译基于对应英文版本页面在 content/en/<some-path>/page.md 的特定main 分支提交。在此仓库中，每个本地化页面都在本地化页面的前端中标识英文页面提交，如下所示：

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

上面的前端将在 content/<some-path>/page.md 中。提交哈希将对应于 main 分支中 content/en/<some-path>/page.md 的最新提交。

跟踪英文页面的更改

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

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

您可以通过提供如下路径来限制目标页面到一个或多个本地化语言：

npm run check:i18n -- content/zh

查看更改详情

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

$ npm run check:i18n -- -d content/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/docs/concepts

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

npm run check:i18n -- -n

为现有页面更新 default_lang_commit

在更新您的本地化页面以匹配相应英文页面所做的更改时，请确保您也更新 default_lang_commit 提交哈希。

如果您已批量更新了所有已偏差的本地化页面，您可以使用 -c 标志后跟提交哈希或‘HEAD’（使用 main@HEAD）来更新这些文件的提交哈希。

npm run check:i18n -- -c <hash> <PATH-TO-YOUR-NEW-FILES>
npm run check:i18n -- -c HEAD <PATH-TO-YOUR-NEW-FILES>

偏差状态

运行 npm run fix:i18n:status 为已发生偏差的目标本地化页面添加前端字段 drifted_from_default。该字段将很快用于在已相对于英文版本发生偏差的页面顶部显示横幅。

脚本帮助

有关该脚本的更多详细信息，请运行 npm run check:i18n -- -h。

新的本地化

有兴趣为 OTel 网站启动新的本地化吗？请联系维护者表达您的兴趣，例如通过 GitHub 讨论或通过 Slack #otel-docs-localization 频道。本节介绍了启动新本地化所涉及的步骤。

1. 组建本地化团队

创建本地化就是发展一个活跃且支持性的社区。要为 OpenTelemetry 网站启动新的本地化，您需要

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

2. 本地化启动：创建问题

在本地化团队到位或正在形成时，创建一个包含以下任务列表的问题：

  1. 查找您想添加的语言的官方ISO 639-1 代码。在本节的其余部分，我们将此语言代码称为 LANG_ID。如果您不确定使用哪个标签，尤其是在选择子区域时，请咨询维护者。

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

  3. 在新问题中包含以下任务列表作为开头的评论：

    - [ ] 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.org.cn/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.org.cn/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.org.cn/docs/contributing/localization/#glossary).

3. 本地化主页

提交一个拉取请求，其中包含网站主页的翻译，*仅此内容*，文件名为 content/LANG_ID/_index.md。确保维护者拥有编辑您 PR 的必要权限，因为他们将在您的 PR 中添加其他更改，以启动您的本地化项目。

您的第一个 PR 合并后，维护者将设置问题标签、组织级别组和组件所有者。

4. 本地化术语表

第二个需要本地化的页面是术语表。这对本地化读者来说是关键页面，因为它定义了可观测性，特别是 OpenTelemetry 中使用的关键术语。如果您的语言中没有这些术语，这一点尤其重要。

有关指导，请参阅 Ali Dowair 在 Write the Docs 2024 的演讲视频：《翻译的艺术：如何本地化 Kubernetes 文档到阿拉伯语》 Ali Dowair。

5. 分小批次本地化剩余的网站页面

在术语确定后，您现在可以本地化剩余的网站页面。

OTel 维护者清单

Hugo

更新 Hugo 的 LANG_ID 配置。在

  • config/_default/hugo.yaml 的 languages 中添加 LANG_ID 的相应条目
  • 通过 config/_default/module-template.yaml 更新 module.mounts。至少，为 content 添加单个 source-target 条目。一旦本地化语言有足够的内容，请考虑仅为 en 回退页面添加条目。

拼写

查找可用的 NPM 包 @cspell/dict-LANG_ID 格式的 cSpell 词典。如果您的方言或地区没有可用的词典，请选择最接近的地区。

如果没有可用的词典，则跳过此小节的其余部分。否则：

  • 将 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 支持：如果 LANG_ID 在 Prettier 中支持不佳，请向 .prettierignore 添加忽略规则

审批者和维护者指南

包含语义更改的 PR 不应跨越多个区域设置

审批者应确保进行文档页面语义更改的PR不应跨越多个区域设置。语义更改是指影响页面内容含义的更改。我们的文档本地化流程确保各区域设置的审批者将及时审查英文语言的编辑，以确定更改是否适合其区域设置，以及如何最好地将其纳入其区域设置。如果需要更改，区域设置审批者将通过其各自的区域设置特定 PR 来进行。

纯粹的编辑性页面更新是指不影响现有内容且可以跨越多个区域设置的更改。这些包括：

  • 链接维护：当页面移动或删除时修复损坏的链接路径。
  • 资源更新：更新指向已移动的外部资源的链接。
  • 定向内容添加：在已偏差文件中添加特定的新定义或部分，当无法更新整个文件时。

例如，有时英文文档的更改可能导致非英语本地化语言出现链接检查失败。当文档页面被移动或删除时，就会发生这种情况。

在这种情况下，对每个出现链接路径失败的非英语页面进行以下更新：

  • 更新链接引用到新的页面路径。
  • 在 default_lang_commit 前端行的末尾添加 # patched YAML 注释。
  • 不要对文件进行其他更改。
  • 重新运行 npm run check:links 并确保没有链接失败。

当一个指向已移动（但否则在语义上未更改）资源（如 GitHub 文件）的外部链接导致链接检查失败时，请考虑：

  • 从 refcache 中删除损坏的链接
  • 使用本节前面描述的方法跨所有本地化语言更新链接。

对已偏差文件的定向内容添加

当向已偏差英文版本的本地化文件添加特定新内容时，您可以选择进行定向更新，而不是更新整个文件。例如，当一个新术语如“基数”（cardinality）添加到英文术语表中时，您可以只将该术语添加到本地化术语表中，而不处理其他已偏差的内容。

以下是此定向更新工作流程的示例：

  • 仅将“基数”定义块添加到本地化术语表中
  • 通过在 default_lang_commit 行末尾添加 # patched 作为注释来更新前端
  • 保持所有其他现有内容不变
  • 在 PR 描述中，清楚地记录：
    • 添加的具体内容（“基数”定义）
    • 该文件在其他内容方面仍有偏差
    • 定向更新的理由（例如，“为本地化读者提供关键的新术语，而无需进行完整文件同步”）

这种方法能够对本地化内容进行渐进式改进，同时保持对文件仍需要未来关注以与英文版本完全同步的认知。

  1. 有关可能的例外，请参阅链接。 ↩︎

  2. Hugo 在渲染跨站点本地化共享的图像文件方面非常智能。也就是说，Hugo 将输出一个单一的图像文件并在不同本地化语言之间共享。 ↩︎


最后修改于 2025 年 10 月 31 日：[CI/i18n] Contrib docs update and hugo.yaml config cleanup (#8302) (e67e24ba)