本地化 Kubernetes 文档

此页面展示了如何将文档本地化为不同的语言。

贡献现有的本地化版本

你可以帮助添加或改进现有本地化版本的内容。在Kubernetes Slack 中，你可以找到每个本地化版本对应的频道。还有一个通用的SIG Docs Localizations Slack 频道，你可以在这里打个招呼。

查找你的两字母语言代码

首先，查阅 ISO 639-1 标准来查找你的本地化版本的两字母语言代码。例如，韩语的两字母代码是 ko。

有些语言使用 ISO-3166 定义的两位国家代码的小写形式以及其语言代码。例如，巴西葡萄牙语的语言代码是 pt-br。

Fork 并克隆仓库

首先，创建你自己的 kubernetes/website 仓库的 Fork。

然后，克隆你的 fork 并 cd 进入它

git clone https://github.com/<username>/website
cd website

网站内容目录包含每种语言的子目录。你想要贡献的本地化内容位于 content/<两字母代码> 内部。

建议修改

根据原始的英文版本创建或更新你选择的本地化页面。有关更多详细信息，请参阅本地化内容。

如果你发现上游（英文）文档存在技术不准确或其他问题，应先修复上游文档，然后通过更新你正在处理的本地化版本来重复等效的修复。

拉取请求中的更改应限制在单一本地化版本。审查更改多个本地化版本内容的拉取请求会带来问题。

遵循内容改进建议来为该本地化版本提出修改。这个过程与为上游（英文）内容提出修改类似。

启动新的本地化版本

如果你想将 Kubernetes 文档本地化为一种新语言，你需要做以下事情。

由于贡献者无法批准自己的拉取请求，因此开始本地化需要**至少两名贡献者**。

所有本地化团队都必须自给自足。Kubernetes 网站乐于托管你的工作，但你需要负责翻译并保持现有本地化内容的最新。

你需要知道你的语言的两字母语言代码。查阅ISO 639-1 标准来查找你的本地化版本的两字母语言代码。例如，韩语的两字母代码是 ko。

如果你要开始本地化的语言在不同地区有显著的变体差异，那么将小写的 ISO-3166 国家代码与语言两字母代码结合起来可能更有意义。例如，巴西葡萄牙语的本地化版本是 pt-br。

当你开始一个新的本地化版本时，你必须将所有最低要求内容本地化，然后 Kubernetes 项目才能将你的更改发布到实时网站。

SIG Docs 可以帮助你在单独的分支上工作，以便你可以逐步实现该目标。

寻找社区

让 Kubernetes SIG Docs 知道你对创建本地化版本感兴趣！加入SIG Docs Slack 频道和SIG Docs Localizations Slack 频道。其他本地化团队乐于帮助你入门并回答你的问题。

还请考虑参加SIG Docs 本地化子小组会议。SIG Docs 本地化子小组的任务是与 SIG Docs 各本地化团队协作，定义和记录创建本地化贡献指南的流程。此外，SIG Docs 本地化子小组寻求机会创建并在各本地化团队之间共享常用工具，并为 SIG Docs 领导团队确定新的需求。如果你对此会议有任何疑问，请在SIG Docs Localizations Slack 频道询问。

你还可以在 kubernetes/community 仓库中为你的本地化版本创建一个 Slack 频道。有关添加 Slack 频道的示例，请参见为波斯语添加频道的 PR。

加入 Kubernetes GitHub 组织

当你提交本地化 PR 后，你可以成为 Kubernetes GitHub 组织的成员。团队中的每个人都需要在 kubernetes/org 仓库中创建自己的组织成员请求。

在 GitHub 中添加你的本地化团队

接下来，将你的 Kubernetes 本地化团队添加到sig-docs/teams.yaml。有关添加本地化团队的示例，请参见添加西班牙语本地化团队的 PR。

@kubernetes/sig-docs-**-owners 的成员可以批准更改你的本地化目录（且仅限此目录）内内容的 PR：/content/**/。对于每个本地化版本，@kubernetes/sig-docs-**-reviews 团队会自动为新的 PR 分配审查任务。@kubernetes/website-maintainers 的成员可以创建新的本地化分支来协调翻译工作。@kubernetes/website-milestone-maintainers 的成员可以使用 /milestone Prow 命令为问题或 PR 分配里程碑。

配置工作流程

接下来，在 kubernetes/test-infra 仓库中为你的本地化版本添加一个 GitHub 标签。标签允许你筛选特定语言的问题和拉取请求。

有关添加标签的示例，请参见添加意大利语标签的 PR。

修改站点配置

Kubernetes 网站使用 Hugo 作为其 Web 框架。网站的 Hugo 配置位于 hugo.toml 文件中。你需要修改 hugo.toml 以支持新的本地化版本。

在 hugo.toml 中现有的 [languages] 块下为新语言添加一个配置块。例如，德语块如下所示

[languages.de]
title = "Kubernetes"
languageName = "Deutsch (German)"
weight = 5
contentDir = "content/de"
languagedirection = "ltr"

[languages.de.params]
time_format_blog = "02.01.2006"
language_alternatives = ["en"]
description = "Produktionsreife Container-Orchestrierung"
languageNameLatinScript = "Deutsch"

语言选择栏列出了 languageName 的值。将“本地脚本和语言中的语言名称（拉丁脚本中的英语语言名称）”赋给 languageName。例如，languageName = "한국어 (Korean)" 或 languageName = "Deutsch (German)"。

languageNameLatinScript 可用于访问拉丁脚本中的语言名称并在主题中使用。将“拉丁脚本中的语言名称”赋给 languageNameLatinScript。例如，languageNameLatinScript ="Korean" 或 languageNameLatinScript = "Deutsch"。

weight 参数决定了语言选择栏中语言的顺序。较低的权重优先级较高，导致语言首先出现。在分配 weight 参数时，务必检查现有的语言块并调整它们的权重，以确保它们相对于所有语言（包括任何新添加的语言）处于排序状态。

有关 Hugo 多语言支持的更多信息，请参见“多语言模式”。

添加新的本地化目录

在仓库的content文件夹中添加一个特定语言的子目录。例如，德语的两字母代码是 de

mkdir content/de

你还需要在 i18n 中为本地化字符串创建一个目录；可以参考现有的本地化版本作为示例。

例如，德语的字符串位于 i18n/de.toml 中。

本地化社区行为准则

针对 cncf/foundation 仓库提交一个 PR，以添加你的语言版本的行为准则。

设置 OWNERS 文件

要设置贡献本地化版本的每个用户的角色，在特定语言子目录中创建一个包含以下内容的 OWNERS 文件：

有关 OWNERS 文件的更多信息，请参见 go.k8s.io/owners。

西班牙语 OWNERS 文件，语言代码为 es，如下所示

# See the OWNERS docs at https://go.k8s.io/owners

# This is the localization project for Spanish.
# Teams and members are visible at https://github.com/orgs/kubernetes/teams.

reviewers:
- sig-docs-es-reviews

approvers:
- sig-docs-es-owners

labels:
- area/localization
- language/es

添加特定语言的 OWNERS 文件后，使用用于本地化的新 Kubernetes 团队 sig-docs-**-owners 和 sig-docs-**-reviews 更新根目录下的 OWNERS_ALIASES 文件。

对于每个团队，按照字母顺序添加在在 GitHub 中添加你的本地化团队中请求的 GitHub 用户列表。

--- a/OWNERS_ALIASES
+++ b/OWNERS_ALIASES
@@ -48,6 +48,14 @@ aliases:
     - stewart-yu
     - xiangpengzhao
     - zhangxiaoyu-zidif
+  sig-docs-es-owners: # Admins for Spanish content
+    - alexbrand
+    - raelga
+  sig-docs-es-reviews: # PR reviews for Spanish content
+    - alexbrand
+    - electrocucaracha
+    - glo-pena
+    - raelga
   sig-docs-fr-owners: # Admins for French content
     - perriea
     - remyleone

提交拉取请求

接下来，提交一个拉取请求 (PR)，将本地化版本添加到 kubernetes/website 仓库。该 PR 必须包含所有最低要求内容才能获得批准。

有关添加新本地化版本的示例，请参见启用法语文档的 PR。

添加本地化的 README 文件

为了指导其他本地化贡献者，在 kubernetes/website 仓库的顶层添加一个新的 README-**.md 文件，其中 ** 是两字母语言代码。例如，德语 README 文件将是 README-de.md。

在本地化的 README-**.md 文件中指导本地化贡献者。包含与 README.md 相同的信息，此外还包括：

  • 本地化项目的联系人
  • 任何特定于该本地化版本的信息

创建本地化 README 后，在主要的英文 README.md 中添加指向该文件的链接，并包含英文联系信息。你可以提供 GitHub ID、电子邮件地址、Slack 频道或任何其他联系方式。你还必须提供本地化社区行为准则的链接。

启动新的本地化版本

当本地化版本满足工作流程和最低输出要求时，SIG Docs 会执行以下操作：

本地化内容

本地化 Kubernetes 的**所有**文档是一项巨大的任务。从小处着手，逐步扩展是可以接受的。

最低要求内容

至少，所有本地化版本必须包含：

描述URL
主页所有一级和二级标题的 URL
安装所有一级和二级标题的 URL
教程Kubernetes 基础，Hello Minikube
站点字符串在新本地化 TOML 文件中的所有站点字符串
发布版本所有一级和二级标题的 URL

翻译后的文档必须位于其各自的 content/**/ 子目录中，但其 URL 路径应与英文源文件相同。例如，要准备将Kubernetes 基础教程翻译成德语，请在 content/ 目录下创建一个子目录，并复制英文源文件或目录。

mkdir -p content/docs/tutorials
cp -ra content/en/docs/tutorials/kubernetes-basics/ content/docs/tutorials/

翻译工具可以加快翻译过程。例如，一些编辑器提供了可以快速翻译文本的插件。

为确保语法和意义的准确性，你的本地化团队成员应在发布前仔细审查所有机器生成的翻译。

本地化 SVG 图像

Kubernetes 项目建议尽可能使用矢量 (SVG) 图像，因为本地化团队更容易编辑它们。如果你发现需要本地化的栅格图像，请首先考虑将英文版本重新绘制为矢量图像，然后再将其本地化。

在翻译 SVG（可缩放矢量图形）图像中的文本时，务必遵循某些准则，以确保准确性并保持不同语言版本之间的一致性。SVG 图像通常用于 Kubernetes 文档中，以说明概念、工作流程和图表。

  1. 识别可翻译文本：首先识别 SVG 图像中需要翻译的文本元素。这些元素通常包括标签、标题、注释或任何传达信息的文本。

  2. 编辑 SVG 文件：SVG 文件是基于 XML 的，这意味着可以使用文本编辑器进行编辑。但是，请务必注意，Kubernetes 中的大多数文档图像已将文本转换为曲线，以避免字体兼容性问题。在这种情况下，建议使用专门的 SVG 编辑软件（例如 Inkscape）进行编辑，打开 SVG 文件并找到需要翻译的文本元素。

  3. 翻译文本：将原始文本替换为所需语言的翻译版本。确保翻译后的文本准确传达预期含义并适合图像中的可用空间。对于使用拉丁字母的语言，应使用 Open Sans 字体系列。你可以在此处下载 Open Sans 字体：Open Sans 字体。

  4. 将文本转换为曲线：如前所述，为解决字体兼容性问题，建议将翻译后的文本转换为曲线或路径。将文本转换为曲线可确保最终图像正确显示翻译后的文本，即使用户的系统未安装原始 SVG 中使用的确切字体。

  5. 审查和测试：进行必要的翻译并将文本转换为曲线后，保存并审查更新后的 SVG 图像，以确保文本正确显示和对齐。检查在本地预览你的更改。

源文件

本地化版本必须基于本地化团队指定的特定发布版本中的英文文件。每个本地化团队可以决定要针对哪个发布版本，以下称为**目标版本**。

查找你的目标版本的源文件

  1. 导航到 Kubernetes 网站仓库：https://github.com/kubernetes/website。

  2. 从下表中选择你的目标版本的 Git 分支

目标版本分支
最新版本main
上一版本release-1.32
下一版本dev-1.34

main 分支包含当前发布版本 v1.33 的内容。发布团队会在下一个发布版本 v1.34 发布之前创建一个 release-1.33 分支。

i18n 中的站点字符串

本地化版本必须在新的特定语言文件中包含 i18n/en/en.toml 的内容。以德语为例：i18n/de.toml。

向 i18n/ 中添加新的本地化目录和文件。例如，对于德语 (de)

mkdir -p i18n/de
cp i18n/en/en.toml i18n/de.toml

修改文件顶部的注释以适应你的本地化版本，然后翻译每个字符串的值。例如，这是德语搜索表单的占位符文本

[ui_search]
other = "Suchen"

本地化站点字符串允许你自定义站点范围的文本和功能：例如，页面页脚中的法律版权文本。

特定语言本地化指南

作为一个本地化团队，你可以通过创建特定语言的本地化指南来规范团队遵循的最佳实践。

例如，请参阅韩语本地化指南，其中包含以下主题的内容

  • 冲刺周期和发布版本
  • 分支策略
  • 拉取请求工作流程
  • 风格指南
  • 已本地化和未本地化术语表
  • Markdown 约定
  • Kubernetes API 对象术语

特定语言的 Zoom 会议

如果本地化项目需要单独的会议时间，请联系 SIG Docs 联席主席或技术负责人创建一个新的周期性 Zoom 会议和日历邀请。只有当团队规模足够大以支持并需要单独会议时才需要这样做。

根据 CNCF 策略，本地化团队必须将其会议上传到 SIG Docs YouTube 播放列表。SIG Docs 联席主席或技术负责人可以帮助完成此过程，直到 SIG Docs 实现自动化。

分支策略

由于本地化项目是高度协作的努力，我们鼓励团队在共享的本地化分支中工作，尤其是在刚开始且本地化尚未上线时。

在本地化分支上协作

  1. @kubernetes/website-maintainers 的团队成员在 https://github.com/kubernetes/website 上从源分支打开一个本地化分支。

    当你将本地化团队添加到 kubernetes/org 仓库时，你的团队批准人已加入 @kubernetes/website-maintainers 团队。

    我们推荐以下分支命名方案：

    dev-<源版本>-<语言代码>.<团队里程碑>

    例如，德语本地化团队的批准人直接在 kubernetes/website 仓库中打开本地化分支 dev-1.12-de.1，该分支基于 Kubernetes v1.12 的源分支。

  2. 个人贡献者基于本地化分支打开特性分支。

    例如，一名德语贡献者从 username:local-branch-name 向 kubernetes:dev-1.12-de.1 提交包含更改的拉取请求。

  3. 批准人审查特性分支并将其合并到本地化分支。

  4. 定期地，批准人通过打开并批准新的拉取请求，将本地化分支与其源分支合并。在批准拉取请求之前，务必 Squash Commit（合并提交）。

根据需要重复步骤 1-4，直到本地化完成。例如，随后的德语本地化分支将是：dev-1.12-de.2、dev-1.12-de.3 等。

团队必须将本地化内容合并到与内容来源相同的分支。例如：

  • 源自 main 的本地化分支必须合并到 main 中。
  • 源自 release-1.32 的本地化分支必须合并到 release-1.32 中。

在每个团队里程碑开始时，打开一个 Issue 来比较上一个本地化分支和当前本地化分支之间的上游更改是有帮助的。有两种脚本可以比较上游更改。

虽然只有批准人可以打开新的本地化分支并合并拉取请求，但任何人都可以为新的本地化分支打开拉取请求。无需特殊权限。

有关从分支或直接从仓库工作的更多信息，请参阅“Fork 并克隆仓库”。

上游贡献

SIG Docs 欢迎对英文源进行上游贡献和更正。

上次修改时间：2025 年 3 月 9 日下午 5:54 PST：feat: 使用 docsy 提供的 ui_search 替换 ui_search_placeholder (4df04ed775)