本地化 Kubernetes 文档

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

起步

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

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

找到两个字母的语言代码

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

派生(fork)并且克隆仓库

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

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

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

发起拉取请求(PR)

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

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

有关添加新本地化的示例,请参见添加法语文档 的 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 命令 为 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 文件看起来像:

# 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-**-ownerssig-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

翻译文档

本地化所有 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.19 中的英文文件。

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

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

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

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/website-maintainers 中的团队成员从 https://github.com/kubernetes/website 原有分支新建一个开发分支。 当你给 kubernetes/org 仓库添加你的本地化团队时, 你的团队批准人便加入了 @kubernetes/website-maintainers 团队。

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

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

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

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

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

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

  3. 批准人会定期发起并批准新的 PR,将开发分支合并到其源分支。在批准 PR 之前,请确保先 squash commits。

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

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

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

在团队每个里程碑的起点,创建一个 issue 来比较先前的开发分支和当前的开发分支之间的上游变化很有帮助。 虽然只有批准人才能创建新的开发分支并合并 PR,但任何人都可以为新的开发分支提交一个拉取请求(PR)。 不需要特殊权限。

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

上游贡献

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

帮助现有的本地化

您还可以向现有本地化添加或改进内容提供帮助。 加入本地化团队的 Slack 频道, 然后开始新建 PR 来提供帮助。 请限制每个 PR 只涉及一种语言,这是因为更改多种语言版本内容的 PR 可能非常难审阅。

接下来

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

最后修改 September 18, 2020 at 5:42 PM PST: add missing links in/zh/docs/home/contribute (1fc81d375)