From 1698263ca3c710251d4ae7dec221d87d0e2aaca3 Mon Sep 17 00:00:00 2001 From: howieyuen Date: Fri, 20 Aug 2021 20:12:39 +0800 Subject: [PATCH] [zh]sync contribution files for 1.22(Part-3) --- content/zh/docs/contribute/localization.md | 390 ++++++++++++++------- 1 file changed, 255 insertions(+), 135 deletions(-) diff --git a/content/zh/docs/contribute/localization.md b/content/zh/docs/contribute/localization.md index 3e58721357..3e5fe68e9e 100644 --- a/content/zh/docs/contribute/localization.md +++ b/content/zh/docs/contribute/localization.md @@ -32,30 +32,41 @@ This page shows you how to [localize](https://blog.mozilla.org/l10n/2011/12/14/i -## 起步 +## 为现有的本地化做出贡献 -由于贡献者无法批准他们自己的请求，因此您至少需要两个贡献者才能开始本地化。 +你可以帮助添加或改进现有本地化的内容。在 [Kubernetes Slack](https://slack.k8s.io/) 中， +你能找到每个本地化的频道。还有一个通用的 +[SIG Docs Localizations Slack 频道](https://kubernetes.slack.com/messages/sig-docs-localizations)， +你可以在这里打个招呼。 -所有本地化团队必须使用自身的资源持续工作。我们很高兴托管你的产出，但无法为你翻译。 +{{< note >}} + +如果你想处理已经存在的本地化，请在该本地化（如果存在）中检查此页面，而不是英文原版。 +你可能会在那里看到额外的详细信息。 +{{< /note >}} ### 找到两个字母的语言代码 -首先，有关本地化的两个字母的国家代码，请参考 +首先，有关本地化的两个字母的语言代码，请参考 [ISO 639-1 标准](https://www.loc.gov/standards/iso639-2/php/code_list.php)。 例如，韩国的两个字母代码是 `ko`。 @@ -74,23 +85,110 @@ git clone https://github.com//website cd website ``` +网站内容目录包括每种语言的子目录。你想要助力的本地化位于 `content/` 中。 + -### 发起拉取请求（PR）{#open-a-pull-request} +### 建议更改 {#suggest-changes} -接下来，[提交 PR 请求](/zh/docs/contribute/new-content/open-a-pr/#open-a-pr)， -将本地化添加到 `kubernetes/website` 仓库。 +根据英文原件创建或更新你选择的本地化页面。 +有关更多详细信息，请参阅[翻译内容](#translating-content)。 -该 PR 必须包含所有[最低要求的内容](#minimum-required-content)，然后才能被批准。 +如果你发现上游（英文）文档存在技术错误或其他问题， +你应该先修复上游文档，然后通过更新你正在处理的本地化来重复等效的修复。 -有关添加新本地化的示例，请参见添加[法语文档](https://github.com/kubernetes/website/pull/12548) 的 PR。 +请将拉取请求限制为单个本地化，因为在多个本地化中更改内容的拉取请求可能难以审查。 + +按照[内容改进建议](/zh/docs/contribute/suggest-improvements/)提出对该本地化的更改。 +该过程与提议更改上游（英文）内容非常相似。 + + +## 开始新的本地化 + +如果你希望将 Kubernetes 文档本地化为一种新语言，你需要执行以下操作。 + +因为贡献者不能批准他们自己的拉取请求，你需要 _至少两个贡献者_ 来开始本地化。 + +所有本地化团队都必须能够自我维持。 +Kubernetes 网站很乐意托管你的作品，但要由你来翻译它并使现有的本地化内容保持最新。 + + +你需要知道你的语言的两个字母的语言代码。 +请查阅 [ISO 639-1 标准](https://www.loc.gov/standards/iso639-2/php/code_list.php) +以查找你的本地化的两字母语言代码。例如，韩语的两字母代码是`ko`。 + +当你开始新的本地化时，你必须先本地化所有[最少要求的内容](#minimum-required-content)， +Kubernetes 项目才能将你的更改发布到当前网站。 + +SIG Docs 可以帮助你在单独的分支上工作，以便你可以逐步实现该目标。 + + +### 找到社区 + +让 Kubernetes SIG Docs 知道你有兴趣创建本地化！ +加入 [SIG Docs Slack 频道](https://kubernetes.slack.com/messages/sig-docs) +和 [SIG Docs Localizations Slack 频道](https://kubernetes.slack.com/messages/sig-docs-localizations)。 +其他本地化团队很乐意帮助你入门并回答你的任何问题。 + + +也请考虑参加 +[SIG Docs 本地化小组的会议](https://github.com/kubernetes/community/tree/master/sig-docs)。 +SIG Docs 本地化小组的任务是与 SIG Docs 本地化团队合作， +共同定义和记录创建本地化贡献指南的流程。 +此外，SIG Docs 本地化小组将寻找机会在本地化团队中创建和共享通用工具， +并为 SIG Docs 领导团队确定新要求。如果你对本次会议有任何疑问， +请在 [SIG Docs Localizations Slack 频道](https://kubernetes.slack.com/messages/sig-docs-localizations) +中提问。 + +你还可以在 `kubernetes/community` 仓库中为你的本地化创建一个 Slack 频道。 +有关添加 Slack 频道的示例，请参阅 +[为波斯语添加频道](https://github.com/kubernetes/community/pull/4980)的 PR。 ### 配置工作流程 {#configure-the-workflow} -接下来，在 `kubernetes/test-infra` 仓库中为您的本地化添加一个 GitHub 标签。 -标签可让您过滤 issues 和针对特定语言的 PR。 +接下来，在 `kubernetes/test-infra` 仓库中为你的本地化添加一个 GitHub 标签。 +标签可让你过滤 issues 和针对特定语言的 PR。 有关添加标签的示例，请参见添加[意大利语标签](https://github.com/kubernetes/test-infra/pull/11316)的 PR。 - -### 寻找社区 - -让 Kubernetes SIG Docs 知道你对创建本地化感兴趣！ -加入[SIG Docs Slack 频道](https://kubernetes.slack.com/messages/C1J0BPD2M/)。 -其他本地化团队很乐意帮助你起步并回答你的任何问题。 - 你还可以在 `kubernetes/community` 仓库中为你的本地化创建一个 Slack 频道。 有关添加 Slack 频道的示例，请参见[为印尼语和葡萄牙语添加频道](https://github.com/kubernetes/community/pull/3605)的 PR。 @@ -175,8 +258,8 @@ Add a configuration block for the new language to `config.toml`, under the exist ### 修改站点配置 Kubernetes 网站使用 Hugo 作为其 Web 框架。网站的 Hugo 配置位于 -[`config.toml`](https://github.com/kubernetes/website/tree/master/config.toml)文件中。 -为了支持新的本地化，您需要修改 `config.toml`。 +[`config.toml`](https://github.com/kubernetes/website/tree/main/config.toml)文件中。 +为了支持新的本地化，你需要修改 `config.toml`。 在现有的 `[languages]` 下，将新语言的配置添加到 `config.toml` 中。 例如，下面是德语的配置示例： @@ -207,7 +290,7 @@ Add a language-specific subdirectory to the [`content`](https://github.com/kuber ### 添加一个新的本地化目录 将特定语言的子目录添加到仓库中的 -[`content`](https://github.com/kubernetes/website/tree/master/content) 文件夹下。 +[`content`](https://github.com/kubernetes/website/tree/main/content) 文件夹下。 例如，德语的两个字母的代码是 `de`： ```shell @@ -215,7 +298,27 @@ mkdir content/de ``` +你还需要在 `data/i18n` 中为 [localized strings](#site-strings-in-i18n) 创建一个目录； +以现有的本地化为例。要使用这些新字符串， +你还必须创建从 `i18n/.toml` +到 `data/i18n//.toml` +中实际字符串配置的符号链接（记得提交符号链接关联）。 + +例如，对于德语，字符串位于 `data/i18n/de/de.toml` 中， +而 `i18n/de.toml` 是指向 `data/i18n/de/de.toml` 的符号链接。 + + -### 添加本地化的 README 文件 - -为了指导其他本地化贡献者，请在 k/website 的根目录添加一个新的 -[`README-**.md`](https://help.github.com/articles/about-readmes/)， -其中 `**` 是两个字母的语言代码。例如，德语 README 文件为 `README-de.md`。 - -在本地化的 `README-**.md` 文件中为本地化贡献者提供指导。包含 `README.md` 中包含的相同信息，以及： - -- 本地化项目的联系人 -- 任何特定于本地化的信息 - - -创建本地化的 README 文件后，请在英语版文件 `README.md` 中添加指向该文件的链接， -并给出英文形式的联系信息。你可以提供 GitHub ID、电子邮件地址、 -[Slack 频道](https://slack.com/)或其他联系方式。你还必须提供指向本地化的社区行为准则的链接。 - +### 打开拉取请求 {#open-a-pull-request} + +接下来，[打开拉取请求](/zh/docs/contribute/new-content/open-a-pr/#open-a-pr)（PR） +将本地化添加到 `kubernetes/website` 存储库。 + +PR 必须包含所有[最低要求内容](#minimum-required-content)才能获得批准。 + +有关添加新本地化的示例， +请参阅 PR 以启用[法语文档](https://github.com/kubernetes/website/pull/12548)。 + + +### 添加本地化的 README 文件 + +为了指导其他本地化贡献者，请在 [k/website](https://github.com/kubernetes/website/) +的根目录添加一个新的 [`README-**.md`](https://help.github.com/articles/about-readmes/)， +其中 `**` 是两个字母的语言代码。例如，德语 README 文件为 `README-de.md`。 + +在本地化的 `README-**.md` 文件中为本地化贡献者提供指导。包含 `README.md` 中包含的相同信息，以及： + +- 本地化项目的联系人 +- 任何特定于本地化的信息 + + +创建本地化的 README 文件后，请在英语版文件 `README.md` 中添加指向该文件的链接， +并给出英文形式的联系信息。你可以提供 GitHub ID、电子邮件地址、 +[Slack 频道](https://slack.com/)或其他联系方式。你还必须提供指向本地化的社区行为准则的链接。 + + +### 启动你的新本地化 + +一旦本地化满足工作流程和最小输出的要求，SIG Docs 将： + +- 在网站上启用语言选择 +- 通过[云原生计算基金会](https://www.cncf.io/about/)（CNCF）渠道， + 包括 [Kubernetes 博客](https://kubernetes.io/blog/)，来宣传本地化的可用性。 + -## 翻译文档 +## 翻译文档 {#translating-content} 本地化*所有* Kubernetes 文档是一项艰巨的任务。从小做起，循序渐进。 @@ -352,15 +491,15 @@ Description | URLs -----|----- Home | [All heading and subheading URLs](/docs/home/) Setup | [All heading and subheading URLs](/docs/setup/) -Tutorials | [Kubernetes Basics](/docs/tutorials/kubernetes-basics/), [Hello Minikube](/docs/tutorials/stateless-application/hello-minikube/) -Site strings | [All site strings in a new localized TOML file](https://github.com/kubernetes/website/tree/master/i18n) +Tutorials | [Kubernetes Basics](/docs/tutorials/kubernetes-basics/), [Hello Minikube](/docs/tutorials/hello-minikube/) +Site strings | [All site strings](#Site-strings-in-i18n) in a new localized TOML file --> 描述 | 网址 -----|----- 主页 | [所有标题和副标题网址](/zh/docs/home/) 安装 | [所有标题和副标题网址](/zh/docs/setup/) 教程 | [Kubernetes 基础](/zh/docs/tutorials/kubernetes-basics/), [Hello Minikube](/zh/docs/tutorials/hello-minikube/) -网站字符串 | [新的本地化 TOML 文件中的所有网站字符串](https://github.com/kubernetes/website/tree/master/i18n) +网站字符串 | [所有网站字符串](#Site-strings-in-i18n) ### 源文件 @@ -421,39 +560,45 @@ The `master` branch holds content for the current release `{{< latest-version >} 目标版本 | 分支 -----|----- + 最新版本 | [`main`](https://github.com/kubernetes/website/tree/main) + 上一个版本 | [`release-{{< skew prevMinorVersion >}}`](https://github.com/kubernetes/website/tree/release-{{< skew prevMinorVersion >}}) 下一个版本 | [`dev-{{< skew nextMinorVersion >}}`](https://github.com/kubernetes/website/tree/dev-{{< skew nextMinorVersion >}}) - 最新版本 | [`master`](https://github.com/kubernetes/website/tree/master) - 之前的版本 | `release-*.**` -`master` 分支中保存的是当前发行版本 `{{< latest-version >}}` 的内容。 +`main` 分支中保存的是当前发行版本 `{{< latest-version >}}` 的内容。 发行团队会在下一个发行版本 v{{< skew nextMinorVersion >}} 出现之前创建 `{{< release-branch >}}` 分支。 -### i18n/ 中的网站字符串 +### i18n/ 中的网站字符串 {#site-strings-in-i18n} 本地化必须在新的语言特定文件中包含 -[`i18n/en.toml`](https://github.com/kubernetes/website/blob/master/i18n/en.toml) -的内容。以德语为例：`i18n/de.toml`。 +[`data/i18n/en/en.toml`](https://github.com/kubernetes/website/blob/master/i18n/en.toml) +的内容。以德语为例：`data/i18n/de/de.toml`。 将新的本地化文件添加到 `i18n/`。例如德语 (`de`)： -```shell -cp i18n/en.toml i18n/de.toml +```bash +mkdir -p data/i18n/de +cp data/i18n/en/en.toml data/i18n/de/de.toml ``` -然后翻译每个字符串的值： + +修改文件顶部的注释以适合你的本地化， +然后翻译每个字符串的值。例如，这是搜索表单的德语占位符文本： -```TOML -[docs_label_i_am] -other = "ICH BIN..." +```toml +[ui_search_placeholder] +other = "Suchen" ``` ### 分支策略 {#branching-strategy} 因为本地化项目是高度协同的工作，所以我们鼓励团队基于共享的本地化分支工作。 +- 特别是在开始并且本地化尚未生效时。 在本地化分支上协作需要： @@ -536,37 +684,38 @@ Teams must merge localized content into the same branch from which the content w For example: -- a localization branch sourced from `master` must be merged into `master`. -- a localization branch sourced from `release-1.19` must be merged into `release-1.19`. +- a localization branch sourced from `main` must be merged into `main`. +- a localization branch sourced from `release-{{ skew "prevMinorVersion" }}` must be merged into `release-{{ skew "prevMinorVersion" }}`. {{< note >}} -If your localization branch was created from `master` branch but it is not merged into `master` before new release branch `{{< release-branch >}}` created, merge it into both `master` and new release branch `{{< release-branch >}}`. To merge your localization branch into new release branch `{{< release-branch >}}`, you need to switch upstream branch of your localization branch to `{{< release-branch >}}`. +If your localization branch was created from `main` branch but it is not merged into `main` before new release branch `{{< release-branch >}}` created, merge it into both `main` and new release branch `{{< release-branch >}}`. To merge your localization branch into new release branch `{{< release-branch >}}`, you need to switch upstream branch of your localization branch to `{{< release-branch >}}`. {{< /note >}} --> 团队必须将本地化内容合入到发布分支中，该发布分支是内容的来源。 例如： -- 源于 `master` 分支的本地化分支必须被合并到 `master`。 -- 源于 `release-1.19` 的本地化分支必须被合并到 `release-1.19`。 +- 源于 `main` 分支的本地化分支必须被合并到 `main`。 +- 源于 `release-{{ skew "prevMinorVersion" }}` + 的本地化分支必须被合并到 `release-{{ skew "prevMinorVersion" }}`。 -如果你的本地化分支是基于 `master` 分支创建的，但最终没有在新的发行 -分支 `{{< release-branch >}}` 被创建之前合并到 `master` 中，需要将其 -同时将其合并到 `master` 和新的发行分支 `{{< release-branch >}}` 中。 +如果你的本地化分支是基于 `main` 分支创建的，但最终没有在新的发行 +分支 `{{< release-branch >}}` 被创建之前合并到 `main` 中，需要将其 +同时将其合并到 `main` 和新的发行分支 `{{< release-branch >}}` 中。 要将本地化分支合并到新的发行分支 `{{< release-branch >}}` 中，你需要 将你本地化分支的上游分支切换到 `{{< release-branch >}}`。 在团队每个里程碑的开始时段，创建一个 issue 来比较先前的本地化分支 和当前的本地化分支之间的上游变化很有帮助。 现在有两个脚本用来比较上游的变化。 -[`upstream_changes.py`](https://github.com/kubernetes/website/tree/master/scripts#upstream_changespy) +[`upstream_changes.py`](https://github.com/kubernetes/website/tree/main/scripts#upstream_changespy) 对于检查对某个文件的变更很有用。 -[`diff_l10n_branches.py`](https://github.com/kubernetes/website/tree/master/scripts#diff_l10n_branchespy) +[`diff_l10n_branches.py`](https://github.com/kubernetes/website/tree/main/scripts#diff_l10n_branchespy) 可以用来为某个特定本地化分支创建过时文件的列表。 虽然只有批准人才能创建新的本地化分支并合并 PR，任何人都可以 @@ -585,32 +734,3 @@ SIG Docs welcomes upstream contributions and corrections to the English source. ### 上游贡献 {#upstream-contributions} Sig Docs 欢迎对英文原文的上游贡献和修正。 - - -## 帮助现有的本地化 - -您还可以向现有本地化添加或改进内容提供帮助。 -加入本地化团队的 [Slack 频道](https://kubernetes.slack.com/messages/C1J0BPD2M/)， -然后开始新建 PR 来提供帮助。 -请限制每个 PR 只涉及一种语言，这是因为更改多种语言版本内容的 PR -可能非常难审阅。 - -## {{% heading "whatsnext" %}} - - -本地化满足工作流程和最低输出要求后，SIG 文档将： - -- 在网站上启用语言选择 -- 通过[Cloud Native Computing Foundation](https://www.cncf.io/about/) (CNCF) 频道, - 包括[ Kubernetes 博客](https://kubernetes.io/blog/)公开本地化的可用性。 -