本地化 Kubernetes 文档

此页面描述如何为其他语言的文档提供本地化版本。

为现有的本地化做出贡献

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

说明：

有关如何为特定本地化做贡献的更多信息，请参阅本页面的各个本地化版本。

找到两个字母的语言代码

首先，有关本地化的两个字母的语言代码，请参考 ISO 639-1 标准。例如，韩语的两个字母代码是 ko。

一些语言使用 ISO-3166 定义的国家代码的小写版本及其语言代码。例如，巴西葡萄牙语代码是 pt-br。

派生（fork）并且克隆仓库

首先，为 kubernetes/website 仓库创建你自己的副本。

然后，克隆你的 website 仓库副本并通过 cd 命令进入 website 目录：

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

网站内容目录包括每种语言的子目录。你想要助力的本地化位于 content/<two-letter-code> 中。

建议更改

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

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

请将 PR 限制为单个语言版本，因为多语言的 PR 内容修改可能难以审查。

按照内容改进建议提出对该本地化的更改。该过程与提议更改上游（英文）内容非常相似。

开始新的本地化

如果你希望将 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 成员可以批准更改对应本地化目录 /content/**/ 中内容的 PR，并仅限这类 PR。对于每个本地化，@kubernetes/sig-docs-**-reviews 团队被自动分派新 PR 的审阅任务。 @kubernetes/website-maintainers 成员可以创建新的本地化分支来协调翻译工作。 @kubernetes/website-milestone-maintainers 成员可以使用 /milestone Prow 命令为 Issue 或 PR 设定里程碑。

配置工作流程

接下来，在 kubernetes/test-infra 仓库中为你的本地化添加一个 GitHub 标签。标签可让你过滤 Issue 和针对特定语言的 PR。

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

修改站点配置

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

在现有的 [languages] 下，将新语言的配置添加到 hugo.toml 中。例如，下面是德语的配置示例：

[languages.de]
title = "Kubernetes"
description = "Produktionsreife Container-Verwaltung"
languageName = "Deutsch (German)"
languageNameLatinScript = "Deutsch"
contentDir = "content/de"
weight = 8

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

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

weight 参数决定语言选择栏中的语言顺序，优先显示权重较低的语言。分配 weight 参数时，检查现有语言块并调整其权重以确保它们相对于所有语言（包括任何新添加的语言）按排序顺序非常重要。

有关 Hugo 多语言支持的更多信息，请参阅"多语言模式"。

添加一个新的本地化目录

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

mkdir content/de

你还需要在 data/i18n 中为本地化字符串创建一个目录；以现有的本地化为例。要使用这些新字符串，你还必须创建从 i18n/<localization>.toml 到 data/i18n/<localization>/<localization>.toml 中实际字符串配置的符号链接（记得提交符号链接关联）。

例如，对于德语，字符串位于 data/i18n/de/de.toml 中，而 i18n/de.toml 是指向 data/i18n/de/de.toml 的符号链接。

本地化社区行为准则

在 cncf/foundation 仓库提交 PR，添加你所用语言版本的行为准则。

设置 OWNERS 文件

要设置每个对本地化做出贡献用户的角色，请在特定于语言的子目录内创建一个 OWNERS 文件，其中：

reviewers：具有评审人角色的 Kubernetes 团队的列表，在本例中为在在 GitHub 中添加你的本地化团队中创建的 sig-docs-**-reviews 团队。
approvers：具有批准人角色的 Kubernetes 团队的列表，在本例中为在在 GitHub 中添加你的本地化团队中创建的 sig-docs-**-owners 团队。
labels：可以自动应用于 PR 的 GitHub 标签列表，在本例中为配置工作流程中创建的语言标签。

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

语言代码为 es 的西班牙语 OWNERS 文件看起来像：

# 参见 OWNERS 文档，位于 https://go.k8s.io/owners

# 这是西班牙语的本地化项目
# 各团队和成员名单位于 https://github.com/orgs/kubernetes/teams

reviewers:
- sig-docs-es-reviews

approvers:
- sig-docs-es-owners

labels:
- language/es

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

对于每个团队，请按字母顺序添加在 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 将：

在网站上启用语言选择
通过云原生计算基金会（CNCF）渠道以及 Kubernetes 博客来宣传本地化的可用性。

本地化文档

本地化所有 Kubernetes 文档是一项艰巨的任务。从小做起，循序渐进。

最低要求内容

所有本地化至少必须包括：

描述	网址
主页	所有标题和副标题网址
安装	所有标题和副标题网址
教程	Kubernetes 基础, Hello Minikube
网站字符串	所有网站字符串
发行版本	所有标题和副标题 URL

翻译后的文档必须保存在自己的 content/**/ 子目录中，否则将遵循与英文源相同的 URL 路径。例如，要准备将 Kubernetes 基础教程翻译为德语，请在 content/de/ 目录下创建一个子目录，并复制英文源文件或目录：

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

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

注意：

机器生成的翻译本身是不够的，本地化需要广泛的人工审核才能满足最低质量标准。

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

本地化 SVG 图片

Kubernetes 项目建议尽可能使用矢量（SVG）图片，因为这些图片对于本地化团队来说更容易编辑。如果你发现一个光栅图（位图）需要本地化翻译，先将英文版本重新绘制为矢量图片，然后再进行本地化。

在翻译 SVG（可缩放矢量图）图片中的文本时，需要遵循几点指导方针，以确保准确性并在不同语言版本之间保持一致。 Kubernetes 文档中常用 SVG 图片来说明概念、工作流和图表。

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

编辑 SVG 文件：SVG 文件是基于 XML 的，这意味着可以使用文本编辑器进行编辑。但请注意 Kubernetes 文档中的大部分图片已经将文本转换为曲线以避免字体兼容性问题。在这种情况下，建议使用 Inkscape 这类专业的 SVG 编辑软件，打开 SVG 文件并定位需要翻译的文本元素。

翻译文本：将原始的文本替换为目标语言的译文。确保翻译的文本准确传达所需的含义，并适配图片中可用的空间。在处理使用拉丁字母的语言时，应使用 Open Sans 字体系列。你可以从此处下载 Open Sans 字体： Open Sans Typeface。

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

检查和测试：完成必要的翻译并将文本转换为曲线后，保存并检查更新后的 SVG 图片，确保文本正确显示和对齐。参考在本地预览你的变更。

源文件

本地化必须基于本地化团队所针对的特定发行版本中的英文文件。每个本地化团队可以决定要针对哪个发行版本，在下文中称作 目标版本（target version）。

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

导航到 Kubernetes website 仓库，网址为 https://github.com/kubernetes/website。
从下面的表格中选择你的目标版本分支：

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

main 分支中保存的是当前发行版本 v1.31 的内容。发行团队会在下一个发行版本 v1.32 出现之前创建 release-1.31 分支。

i18n/ 中的网站字符串

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

将新的本地化文件和目录添加到 data/i18n/。例如德语（de）：

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

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

[ui_search_placeholder]
other = "Suchen"

特定语言的本地化指南

作为本地化团队，你可以通过创建特定语言的本地化指南来正式确定团队需遵循的最佳实践。请参见中文本地化指南。

特定语言的 Zoom 会议

如果本地化项目需要单独的会议时间，请联系 SIG Docs 联合主席或技术主管以创建新的重复 Zoom 会议和日历邀请。仅当团队维持在足够大的规模并需要单独的会议时才需要这样做。

根据 CNCF 政策，本地化团队必须将他们的会议上传到 SIG Docs YouTube 播放列表。 SIG Docs 联合主席或技术主管可以帮助完成该过程，直到 SIG Docs 实现自动化。

分支策略

因为本地化项目是高度协同的工作，特别是在刚开始本地化并且本地化尚未生效时，我们鼓励团队基于共享的本地化分支工作。

在本地化分支上协作需要：

@kubernetes/website-maintainers 中的团队成员从 https://github.com/kubernetes/website 原有分支新建一个本地化分支。
当你给 kubernetes/org 仓库添加你的本地化团队时，你的团队批准人便加入了 @kubernetes/website-maintainers 团队。
我们推荐以下分支命名方案：
dev-<source version>-<language code>.<team milestone>
例如，一个德语本地化团队的批准人基于 Kubernetes v1.12 版本的源分支，直接新建了 kubernetes/website 仓库的本地化分支 dev-1.12-de.1。

个人贡献者基于本地化分支创建新的特性分支。
例如，一个德语贡献者新建了一个拉取请求，并将 username:local-branch-name 更改为 kubernetes:dev-1.12-de.1。
批准人审查功能分支并将其合并到本地化分支中。
批准人会定期发起并批准新的 PR，将本地化分支合并到其源分支。在批准 PR 之前，请确保先 squash commits。

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

团队必须将本地化内容合入到发布分支中，该发布分支是内容的来源。例如：

源于 main 分支的本地化分支必须被合并到 main。
源于 release-{{ skew "prevMinorVersion" }} 的本地化分支必须被合并到 release-{{ skew "prevMinorVersion" }}。

说明：

如果你的本地化分支是基于 main 分支创建的，但最终没有在新的发行分支 release-1.31 被创建之前合并到 main 中，需要将其同时将其合并到 main 和新的发行分支 release-1.31 中。要将本地化分支合并到新的发行分支 release-1.31 中，你需要将你本地化分支的上游分支切换到 release-1.31。

在团队每个里程碑的开始时段，创建一个 issue 来比较先前的本地化分支和当前的本地化分支之间的上游变化很有帮助。现在有两个脚本用来比较上游的变化。

upstream_changes.py 对于检查对某个文件的变更很有用。
diff_l10n_branches.py 可以用来为某个特定本地化分支创建过时文件的列表。

虽然只有批准人才能创建新的本地化分支并合并 PR，任何人都可以为新的本地化分支提交一个拉取请求（PR）。不需要特殊权限。

有关基于派生或直接从仓库开展工作的更多信息，请参见"派生和克隆"。

上游贡献

Sig Docs 欢迎对英文原文的上游贡献和修正。

最后修改 June 20, 2024 at 12:44 PM PST: Sync changest from andygol/k8s-website (36d05bc8a1)