本地化 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文件,其中包含

有关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_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 会执行以下操作:

本地化内容

本地化所有 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 文档中,以说明概念、工作流程和图表。

  1. 识别可翻译文本:首先识别 SVG 图像中需要翻译的文本元素。这些元素通常包括标签、标题、注释或任何传达信息的文本。

  2. 编辑 SVG 文件:SVG 文件是基于 XML 的,这意味着可以使用文本编辑器对其进行编辑。但是,需要注意的是,Kubernetes 中的大多数文档图像已经将文本转换为曲线,以避免字体兼容性问题。在这种情况下,建议使用专业的 SVG 编辑软件(例如 Inkscape)进行编辑,打开 SVG 文件并找到需要翻译的文本元素。

  3. 翻译文本:将原始文本替换为目标语言的翻译版本。确保翻译后的文本准确传达了预期含义,并且适合图像中可用的空间。在处理使用拉丁字母的语言时,应使用 Open Sans 字体系列。您可以从这里下载 Open Sans 字体:Open Sans 字体

  4. 将文本转换为曲线:如前所述,为了解决字体兼容性问题,建议将翻译后的文本转换为曲线或路径。将文本转换为曲线可确保最终图像正确显示翻译后的文本,即使用户的系统没有使用原始 SVG 中的相同字体。

  5. 审查和测试:完成必要的翻译并将文本转换为曲线后,保存并查看更新后的 SVG 图像,以确保文本正确显示并对齐。查看 本地预览您的更改

源文件

本地化必须基于本地化团队目标版本的英文文件。每个本地化团队都可以决定要目标版本,以下称为“目标版本”。

要查找目标版本的源文件,请执行以下操作:

  1. 导航到 Kubernetes 网站仓库,地址为:https://github.com/kubernetes/website

  2. 从下表中选择目标版本的对应分支。

目标版本分支
最新版本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 联合主席或技术负责人可以帮助进行此过程。

分支策略

由于本地化项目是高度协作性的工作,我们鼓励团队在共享的本地化分支中工作,尤其是在刚开始时,本地化尚未上线的情况下。

要在本地化分支上进行协作,请执行以下操作:

  1. @kubernetes/website-maintainers 团队成员从 https://github.com/kubernetes/website 上的源分支创建一个本地化分支。

    当您添加本地化团队kubernetes/org 仓库时,您的团队审批者加入了 @kubernetes/website-maintainers 团队。

    我们建议使用以下分支命名方案:

    dev-<源版本>-<语言代码>.<团队里程碑>

    例如,德语本地化团队的审批者直接在 kubernetes/website 仓库中打开本地化分支 dev-1.12-de.1,该分支基于 Kubernetes v1.12 的源分支。

  2. 个人贡献者基于本地化分支打开功能分支。

    例如,德语贡献者从 username:local-branch-name 打开一个包含对 kubernetes:dev-1.12-de.1 的更改的拉取请求。

  3. 审批者审查并合并功能分支到本地化分支。

  4. 定期地,审批者通过打开并批准一个新的拉取请求,将本地化分支与其源分支合并。在批准拉取请求之前,请务必压缩提交。

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

团队必须将本地化内容合并到与内容源相同的分支中。例如:

  • main 分支创建的本地化分支必须合并到 main 分支中。
  • release-1.30 分支创建的本地化分支必须合并到 release-1.30 分支中。

在每个团队里程碑开始时,打开一个问题以比较上游更改(上一个本地化分支与当前本地化分支之间的更改)非常有用。有两种脚本可用于比较上游更改。

虽然只有审批者可以打开新的本地化分支和合并拉取请求,但任何人都可以为新的本地化分支打开拉取请求。不需要任何特殊权限。

有关从 fork 或直接从仓库中工作的更多信息,请参见 "fork and clone the repo"

上游贡献

SIG Docs 欢迎对英文源文件的贡献和更正。

最后修改时间:2024 年 4 月 17 日下午 4:48 PST:Update content/en/docs/contribute/localization.md (18f0cce616)