为 Kubernetes 文档做贡献

Kubernetes v1.17 版本的文档已不再维护。您现在看到的版本来自于一份静态的快照。如需查阅最新文档,请点击 最新版本。

Edit This Page

本地化 Kubernetes 文档

此页面显示了如何为其他语言的文档提供本地化

入门

由于贡献者无法批准他们自己的请求,因此您至少需要两个贡献者才能开始本地化。

所有本地化团队必须使用自身的资源独立工作。我们很高兴支持你的工作,但无法为你翻译。

找到两个字母的语言代码

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

fork 并且克隆仓库

首先,在 kubernetes/website 仓库中的 fork 你自己的分支

然后,克隆 website 仓库并通过 cd 命令进入 website 目录:

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

发起 pr

接下来,提交 PR 请求,将本地化添加到 kubernetes/website 仓库。

PR 必须包含所有最低要求的内容,然后才能被批准。

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

Join the Kubernetes GitHub organization

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

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

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

sig-docs-**-owners 成员可以批准更改对应本地化目录 /content/**/ 中内容的 PR,并仅限这类 PR。

sig-docs-**-reviews 团队自动分派新 PR 的审阅任务。

sig-docs-l10n-admins 成员可以创建新的开发分支来协调翻译工作。

website-milestone-maintainers 成员可以使用 /milestone Prow 命令 为 issues 或 PR 设定里程碑。

配置工作流程

接下来,在 kubernetes/test-infra 仓库中为您的本地化添加一个 GitHub 标签。标签可让您过滤 issues 并提出针对特定语言的 pr。

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

寻找社区

让 Kubernetes SIG Docs 知道您对创建本地化感兴趣! 加入SIG Docs Slack 频道。其他本地化团队很乐意帮助您入门并回答您的任何问题。

您还可以在 kubernetes/community 存储库中为本地化创建一个 Slack 频道。有关添加 Slack 频道的示例,请参见为印尼语和葡萄牙语添加频道的 PR。

最低要求内容

修改站点配置

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

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

[languages.de]
title = "Kubernetes"
description = "Produktionsreife Container-Verwaltung"
languageName = "Deutsch"
contentDir = "content/de"
weight = 3

为您的块分配一个 weight 参数时,找到权重最高的语言块并将其加 1。

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

添加一个新的本地化目录

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

mkdir content/de

本地化社区行为准则

针对 cncf/foundation 仓库提交 PR,添加您所用语言版本的行为准则。

添加本地化的 README 文件

为了指导其他本地化贡献者,请在 k/website 的根目录添加一个新的 README-**.md,其中 ** 是两个字母的语言代码。例如,德语 README 文件为 README-de.md

在本地化的 README-**.md 文件中为本地化贡献者提供指导。包含 README.md 中包含的相同信息,以及:

  • 本地化项目的联系人
  • 任何有关本地化的信息

创建本地化的 README 文件后,请在英语版文件 README.md 中添加指向该文件的链接,并给出英文形式的联系信息。您可以提供 GitHub ID、电子邮件地址、Slack 频道或其他联系方式。您还必须提供指向本地化的社区行为准则的链接。

设置 OWNERS 文件

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

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

带有语言代码 es西班牙 OWNERS 文件看起来像:

# 在 https://go.k8s.io/owners 地址查看 OWNERS 文档

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

reviewers:
- sig-docs-es-reviews

approvers:
- sig-docs-es-owners

labels:
- language/es

添加了特定语言的 OWNERS 文件之后,使用新的 Kubernetes 团队更新 根目录下的 OWNERS_ALIAES 文件进行本地化,即 sig-docs-**-ownerssig-docs-**-reviews

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

翻译文档

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

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

描述 网址
主页 所有标题和副标题网址
安装 所有标题和副标题网址
教程 Kubernetes 基础, Hello Minikube
网站字符串 新的本地化 TOML 文件中的所有网站字符串

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

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

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

警告: 机器生成的翻译不能达到最低质量标准,需要进行大量人工审查才能达到该标准。

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

源文件

本地化必须基于最新版本 v1.21 中的英文文件。

要查找最新版本的源文件:

  1. 导航到 Kubernetes website 仓库,网址为 https://github.com/kubernetes/website。
  2. 选择最新版本的 release-1.X 分支。

最新版本是 v1.21 ,所以最新的发行分支是 release-1.21

i18n/ 中的网站字符串

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

将新的本地化文件添加到 i18n/。例如德语 (de):

cp i18n/en.toml i18n/de.toml

然后翻译每个字符串的值:

[docs_label_i_am]
other = "ICH BIN..."

本地化网站字符串允许你自定义网站范围的文本和特性:例如,每个页面页脚中的合法版权文本。

特定语言的样式指南和词汇表

一些语言团队有自己的特定语言风格指南和词汇表。例如,请参见韩语本地化指南

分支策略

因为本地化项目是高度协同的工作,所以我们鼓励团队基于共享的开发分支工作。

在开发分支上协作:

  1. @kubernetes/sig-docs-l10n-admins 中的团队成员从 https://github.com/kubernetes/website 原有分支新建一个开发分支。 当您给 kubernetes/org 存储库添加您的本地化团队时,您的团队 approvers 便加入了 sig-docs-l10n-admins

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

    dev-<source version>-<language code>.<team milestone>

    例如,一个德语本地化团队的 approvers 基于 Kubernetes v1.12 版本的源分支直接新建了 k/website 仓库的开发分支 dev-1.12-de.1

  1. 个人贡献者基于开发分支新建特性分支。

    例如,一个德国贡献者新建了一个拉取请求,并将 username:local-branch-name 更改为 kubernetes:dev-1.12-de.1

  2. Approvers 审查功能分支并将其合并到开发分支中。

  3. approver 会定期打开并批准新的 pr,将开发分支合并到其源分支。在批准 pr 之前,请确保先 squash 提交。

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

团队必须将本地化内容合入到发布分支中,该发布分支也正是内容的来源。例如,源于 release-1.21 的开发分支必须基于 release-1.21 。

approver 必须通过使开发分支与源分支保持最新并解决合并冲突来维护开发分支。开发分支的存在时间越长,通常需要的维护工作就越多。考虑定期合并开发分支并新建分支,而不是维护一个持续时间很长的开发分支。

在每个团队里程碑的起点,打开一个 issue 来比较先前的开发分支和当前的开发分支之间的上游变化很有帮助。

虽然只有 approver 才能开启新的开发分支并合并 pr,但任何人都可以为新的开发分支提交一个拉取请求(PR)。不需要特殊权限。

有关基于 fork 或直接从仓库开展工作的更多信息,请参见 “fork 和克隆”

上游贡献

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

帮助现有的本地化

您还可以向现有本地化添加或改进内容提供帮助。加入 Slack 频道进行本地化,然后开始新建 PR 来提供帮助。

接下来

本地化满足工作流程和最低输出要求后,SIG 文档将:

反馈