本地化 Kubernetes 文档
此页面展示了如何本地化不同语言的文档。
为现有本地化贡献力量
您可以帮助添加或改进现有本地化的内容。在Kubernetes Slack中,您可以找到每个本地化的频道。还有一个通用的SIG Docs 本地化 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 本地化 Slack 频道。其他本地化团队很乐意帮助您入门并回答您的问题。
也请考虑参与SIG Docs 本地化小组会议。SIG Docs 本地化小组的使命是在 SIG Docs 本地化团队之间合作,共同定义和记录创建本地化贡献指南的流程。此外,SIG Docs 本地化小组还寻求机会在本地化团队之间创建和共享通用工具,并确定对 SIG Docs 领导团队的新要求。如果您对此会议有任何疑问,请在SIG Docs 本地化 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
以支持新的本地化。
在现有[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 文件如下所示
# 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:
- 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 文件
为了指导其他本地化贡献者,请在 README-**.md
文件的顶层目录中添加一个新的 README 文件,其中 **
代表两位字母的语言代码。例如,一个德语 README 文件将命名为 README-de.md
。
在本地化的 README-**.md
文件中指导本地化贡献者。包含 README.md
文件中的所有信息,以及以下内容:
- 本地化项目的联系人
- 任何特定于本地化的信息
创建完本地化的 README 文件后,请在英文版 README.md
文件中添加指向该文件的链接,并包含英文版的联系信息。您可以提供 GitHub ID、电子邮件地址、Slack 频道 或其他联系方式。您还必须提供指向您本地化社区行为准则的链接。
启动您的新本地化项目
当本地化项目满足工作流程和最低输出要求时,SIG Docs 会执行以下操作:
- 启用网站上的语言选择功能。
- 通过 云原生计算基金会 (CNCF) 渠道宣传本地化项目的可用性,包括 Kubernetes 博客。
本地化内容
本地化所有 Kubernetes 文档是一个巨大的任务。可以从小处着手,随着时间的推移逐步扩展。
最低要求内容
所有本地化项目至少必须包含以下内容:
描述 | URL |
---|---|
主页 | 所有标题和子标题的 URL |
设置 | 所有标题和子标题的 URL |
教程 | Kubernetes 基础,Hello Minikube |
网站字符串 | 在一个新的本地化 TOML 文件中提供 所有网站字符串 |
发布 | 所有标题和子标题的 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 (可缩放矢量图形) 图像中的文本时,必须遵循某些准则,以确保准确性并在不同语言版本之间保持一致性。SVG 图像通常用于 Kubernetes 文档中,以说明概念、工作流程和图表。
识别可翻译文本:首先识别 SVG 图像中需要翻译的文本元素。这些元素通常包括标签、标题、注释或任何传达信息的文本。
编辑 SVG 文件:SVG 文件是基于 XML 的,这意味着可以使用文本编辑器对其进行编辑。但是,需要注意的是,Kubernetes 中的大多数文档图像已经将文本转换为曲线,以避免字体兼容性问题。在这种情况下,建议使用专业的 SVG 编辑软件(例如 Inkscape)进行编辑,打开 SVG 文件并找到需要翻译的文本元素。
翻译文本:将原始文本替换为目标语言的翻译版本。确保翻译后的文本准确传达了预期含义,并且适合图像中可用的空间。在处理使用拉丁字母的语言时,应使用 Open Sans 字体系列。您可以从这里下载 Open Sans 字体:Open Sans 字体。
将文本转换为曲线:如前所述,为了解决字体兼容性问题,建议将翻译后的文本转换为曲线或路径。将文本转换为曲线可确保最终图像正确显示翻译后的文本,即使用户的系统没有使用原始 SVG 中的相同字体。
审查和测试:完成必要的翻译并将文本转换为曲线后,保存并查看更新后的 SVG 图像,以确保文本正确显示并对齐。查看 本地预览您的更改。
源文件
本地化必须基于本地化团队目标版本的英文文件。每个本地化团队都可以决定要目标版本,以下称为“目标版本”。
要查找目标版本的源文件,请执行以下操作:
导航到 Kubernetes 网站仓库,地址为: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"
本地化网站字符串可以让您自定义全站文本和功能:例如,每个页面页脚中的法律版权文本。
特定于语言的本地化指南
作为本地化团队,您可以通过创建特定于语言的本地化指南来规范您的团队遵循的最佳实践。
例如,请参见 韩语本地化指南,其中包含以下主题的内容:
- 冲刺节奏和发布
- 分支策略
- 拉取请求工作流程
- 风格指南
- 本地化和非本地化术语词汇表
- Markdown 约定
- Kubernetes API 对象术语
特定于语言的 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-<源版本>-<语言代码>.<团队里程碑>
例如,德语本地化团队的审批者直接在
kubernetes/website
仓库中打开本地化分支dev-1.12-de.1
,该分支基于 Kubernetes v1.12 的源分支。个人贡献者基于本地化分支打开功能分支。
例如,德语贡献者从
username:local-branch-name
打开一个包含对kubernetes:dev-1.12-de.1
的更改的拉取请求。审批者审查并合并功能分支到本地化分支。
定期地,审批者通过打开并批准一个新的拉取请求,将本地化分支与其源分支合并。在批准拉取请求之前,请务必压缩提交。
根据需要重复步骤 1-4,直到本地化完成。例如,后续的德语本地化分支将是:dev-1.12-de.2
、dev-1.12-de.3
等。
团队必须将本地化内容合并到与内容源相同的分支中。例如:
- 从
main
分支创建的本地化分支必须合并到main
分支中。 - 从
release-1.30
分支创建的本地化分支必须合并到release-1.30
分支中。
注意
如果您的本地化分支是从main
分支创建的,但在创建新的发布分支 release-1.31
之前未合并到 main
中,请将其合并到 main
和新的发布分支 release-1.31
中。要将您的本地化分支合并到新的发布分支 release-1.31
中,您需要将本地化分支的上游分支切换到 release-1.31
。在每个团队里程碑开始时,打开一个问题以比较上游更改(上一个本地化分支与当前本地化分支之间的更改)非常有用。有两种脚本可用于比较上游更改。
upstream_changes.py
可用于检查对特定文件的更改。以及diff_l10n_branches.py
可用于创建特定本地化分支的过时文件列表。
虽然只有审批者可以打开新的本地化分支和合并拉取请求,但任何人都可以为新的本地化分支打开拉取请求。不需要任何特殊权限。
有关从 fork 或直接从仓库中工作的更多信息,请参见 "fork and clone the repo"。
上游贡献
SIG Docs 欢迎对英文源文件的贡献和更正。