中文本地化样式指南

本节详述文档中文本地化过程中须注意的事项。 这里列举的内容包含了中文本地化小组早期给出的指导性建议和后续实践过程中 积累的经验。 在阅读、贡献、评阅中文本地化文档的过程中，如果对本文的指南有任何改进建议， 都请直接提出 PR。我们欢迎任何形式的补充和更正！

一般规定

本节列举一些译文中常见问题和约定。

英文原文的保留

为便于译文审查和变更追踪，所有中文本地化 Markdown 文件中都应使用 HTML 注释 <!-- 和 --> 将英文原文逐段注释起来，后跟对应中文译文。例如：

  1. <!--
  2. This is English text ... 
  3. -->
  4. 中文译文对应 ...

不建议采用下面的方式注释英文段落，除非英文段落非常非常短：

  1. <!-- This is English text ...  -->
  2. 中文译文对应 ...

无论英文原文或者中文译文中，都不要保留过多的、不必要的空白行。

段落划分

请避免大段大段地注释和翻译。一般而言，每段翻译可对应两三个自然段。 段落过长会导致译文很难评阅。但也不必每个段落都单独翻译。例如：

  1. <!--
  2. ## Overview
  4. ### Concept
  6. First paragraph, not very long.
  7. -->
  8. ## 概述 {#overview}
  10. ### 概念 {#concept}
  12. 第一段落，不太长。

以下风格是不必要的：

  1. <!--
  2. ## Overview
  3. -->
  4. ## 概述 {#overview}
  6. <!--
  7. ### Concept
  8. -->
  9. ### 概念 {#concept}
  11. <!--
  12. First paragraph, not very long.
  13. -->
  14. 第一段落，不太长。

编号列表的处理

编号列表需要编号的连续性，处理不好的话可能导致输出结果错误。 由于有些列表可能很长，一次性等将整个列表注释掉再翻译也不现实。 推荐采用下面的方式。

假定英文为：

  1. 1. Prepare something
  2. 1. Followed by a long step with code snippets and notes ...
  3.    this is a really long item
  4. 1. Another long item ...
  5.    .. continues here
  6. 1. Almost done ...

本地化处理：

  1. <!--
  2. 1. Prepare something
  3. -->
  4. 1. 准备工作，...
  5.    这里每行缩进 3 个空格
  7. <!--
  8. 1. Followed by a long step with code snippets and notes ...
  9.    this is a really long item
  10. -->
  11. 2. 这里是第二个编号，但需要显式给出数字，不能沿用英文编号。
  12.    缩进内容同上，3 个空格。
  13.    即使有三个反引号的代码段或者短代码，都按 3 个空格缩进。
  15. <!--
  16. 1. Another long item ...
  17.    .. continues here
  18. 1. Almost done ...
  19. -->
  20. 3. 继续列表。
  22.    如果条目有多个段落，也要
  23.    保持缩进对齐以确保排版正确。
  25. 4. 列表终于结束

Frontmatter 的处理

页面中的 Frontmatter 指的是文件头的两个 --- 中间的部分。 对这一部分，解析器有特殊处理，因此不能将英文部分放在前面，中文跟在后面。 需要将二者顺序颠倒。如下所示：

  1. ---
  2. title: 译文标题
  3. type: concept
  4. weight: 30
  5. ---
  7. <!--
  8. title: English title
  9. type: concept
  10. reviewers:
  11.   - john
  12.   - doe
  13. weight: 30
  14. -->

这里要注意的是：

  • title、description 的内容要翻译，其他字段一般不必（甚至不可）翻译。
  • reviewers 部分要删除，不然中文译文会转给英文作者来审阅。

短代码（shortcode）处理

通过 HTML 注释的短代码仍会被运行，因此需要额外小心。建议处理方式：

  1. <!--
  2. English text
  3. -->
  4. {{< note >}}
  5. 中文译文
  6. {{< /note >}}

评阅人应该不难理解中英文段落的对应关系。但是如果采用下面的方式，则会出现 两个 note，因此需要避免。这是因为被注释起来的短代码仍会起作用！

  1. <!--
  2. {{< note >}}
  3. English text
  4. {{< /note >}}
  5. -->
  6. {{< note >}}
  7. 中文译文
  8. {{< /note >}}

译与不译

资源名称或字段不译

根据英文原文写作风格约定【也在持续修订改进】，对 Kubernetes 中的 API 资源均按其规范中所给的大小写形式书写，例如：英文中会使用 Deployment 而不是 deployment 来表示名为 “Deployment” 的 API 资源类型和对象实例。

对这类词语，一般不应翻译。

说明： 英文原文在这方面并不严谨，译者或中文译文的评阅者要非常留心。 比如 Secret 资源，很多时候被误写为 secret。这时在本地化版本中一定 不能译为“秘密”，以免与原文的语义不符。

代码中的注释

一般而言，代码中的注释需要翻译，包括存放在 content/zh/examples/ 目录下 的清单文件中的注释。

出站链接

如果超级链接的目标是 Kubernetes 网站之外的纯英文网页，链接中的内容可以不翻译。 例如：

  1. <!--
  2. Please check [installation caveats](https://acme.com/docs/v1/caveats) ...
  3. -->
  4. 请参阅 [installation caveats](https://acme.com/docs/v1/caveats) ...

注意，这里的 installation 与 参阅 之间留白，因为解析后属于中英文混排的情况。

标点符号

译文中标点符号要使用全角字符，除非以下两种情况：

  • 标点符号是英文命令的一部分；
  • 标点符号是 Markdown 语法的一部分。

英文排比句式中采用的逗号，在译文中要使用顿号代替，复合中文书写习惯。

更新译文

由于整个文档站点会随着 Kubernetes 项目的开发进展而演化，英文版本的网站内容 会不断更新。鉴于中文站点的基本翻译工作在 1.19 版本已完成，从 1.20 版本开始 本地化的工作会集中在追踪英文内容变化上。

为确保准确跟踪中文化版本与英文版本之间的差异，中文内容的 PR 所包含的每个页面 都必须是“最新的”。这里的“最新”指的是对应的英文页面中的更改已全部同步到中文页面。 如果某中文 PR 中包含对 content/zh/docs/foo/bar.md 的更改，且文件 bar.md 的 上次更改日期是 2020-10-01 01:02:03 UTC，对应 GIT 标签 abcd1234，则 bar.md 应包含自 abcd1234 以来 content/en/docs/foo/bar.md 的所有变更， 否则视此 PR 为不完整 PR，会破坏我们对上游变更的跟踪。

这一要求适用于所有更改，包括拼写错误、格式更正、链接修订等等。要查看文件 bar.md 上次提交以来发生的所有变更，可使用：

  1. ./scripts/lsync.sh content/zh/docs/foo/bar.md

关于链接

链接锚点

英文 Markdown 中的各级标题会自动生成锚点，以便从其他页面中链接。 在译为中文后，相应的链接必然会失效。为防止这类问题，建议在翻译 各级标题时，使用英文方式显式给出链接锚点。例如：

  1. <!--
  2. ### Create a Pod
  3. -->
  4. ### 创建 Pod   {#create-a-pod}

此类问题对于概念部分的页面最为突出，需要格外注意。

中文链接目标

由于大部分页面已经完成中文本地化，这意味着很多链接可以使用中文版本作为目标。 例如：

  1. <!--
  2. For more information, please check [volumes](/docs/concepts/storage/)
  3. ...
  4. -->
  5. 更多的信息可参考[卷](/zh/docs/concepts/storage/)页面。

如果对应目标页面尚未本地化，建议登记一个 Issue。

说明：

Website 的仓库中 scripts/linkchecker.py 是一个工具，可用来检查页面中的链接。 例如，下面的命令检查中文本地化目录 /content/zh/docs/concepts/containers/ 中所有 Markdown 文件中的链接合法性：

  1. ./scripts/linkchecker.py -l zh -f /docs/concepts/containers/**/*.md

排版格式

以下为译文 Markdown 排版格式要求：

  • 中英文之间留一个空格
    • 这里的“英文”包括以英文呈现的超级链接
    • 这里的中文、英文都不包括标点符号
  • 译文 Markdown 中不要使用长行，应适当断行。
    • 可根据需要在 80-120 列断行
    • 最好结合句子的边界断行，即一句话在一行，不必留几个字转到下一行
    • 超级链接文字一般较长，可独立成行

警告： 我们注意到有些贡献者可能使用了某种自动化工具，在 Markdown 英文原文中自动 添加空格。虽然这些工具可一定程度提高效率，仍然需要提请作者注意，某些工具 所作的转换可能是不对的，例如将 foo=bar 转换为 foo = bar、将 ），另一些文字 转换为 ） ，另一些文字 等等，甚至将超级链接中的半角 井号（#）转换为全角，导致链接失效。

英文中 “you” 翻译成 “你” 不必是 “您” 文章内的链接用英文例如 (#deploying )，在对应的标题上后面加上 {#deploying}

术语

术语拼写

按中文译文习惯，尽量不要在中文译文中使用首字母小写的拼写。例如：

  1. 列举所有 pods，查看其创建时间 ...       [No]
  2. 列举所有 Pod，查看其创建时间 ...        [Yes]

第一次使用首字母缩写时，应标注其全称和中文译文。例如：

  1. 你可以创建一个 Pod 干扰预算（Pod Disruption Budget，PDB）来解决这一问题。
  2. 所谓 PDB 实际上是 ...

对于某些特定于 Kubernetes 语境的术语，也应在第一次出现在页面中时给出其英文原文， 以便读者对照阅读。例如：

  1. 镜像策略（Image Policy）用来控制集群可拉取的镜像仓库（Image Registry）源。

术语对照

本节列举常见术语的统一译法。除极个别情况，对于专业术语应使用本节所列举的译法：

  • API Server，API 服务器
  • GA (general availability)，正式发布
  • addons，插件
  • admission controller，准入控制器
  • affinity，亲和性
  • annotation，注解
  • anti-affinity，反亲和性
  • attach，挂接
  • autoscale，自动扩缩容
  • bearer token，持有者令牌
  • capabilities权能字
    • 当泛指某主体执行某操作的能力时，可直译为“能力”
    • 当特指 Linux 操作系统上的权限控制机制时，译为“权能字”
  • certificate authority，证书机构
  • certificate，证书
  • claim，申领
  • cloud provider
    • 当用来指代下层云服务的提供厂商时，译为“云服务供应商”
    • 当特指 Kubernetes 中对不同云平台的支持时，可酌情译为“云驱动”
  • cluster，集群
  • condition
    • 大多数上下文中，可译为“条件”
    • 在讨论 Kubernetes 资源的 condition 时，应译为“状况”
  • control loop，控制回路
  • control plane，控制平面，或控制面
  • controller，控制器
  • controller manager，控制器管理器
  • credential，登录凭据，凭据
  • custom，定制，或自定义
  • daemon，守护进程
  • dashboard，仪表板
  • dependent，附属或附属者
  • deprecated，已弃用的
  • deprecation，弃用
  • desired，预期的
  • desired state，预期状态
  • detach，解除挂接
  • distribution，发行版本
  • disruption，干扰（请勿译为“中断”）
  • drain，腾空
  • endpoint，端点
  • egress，出站
  • evict，驱逐
  • eviction，驱逐
  • feature gate，特性门控
  • federation，联邦
  • flags，命令行参数，参数
  • grace period，宽限期限
  • graceful termination，体面终止
  • hairpin，发夹
  • hash，哈希
  • headless service，无头服务
  • healthcheck，健康检查
  • hook，回调
  • host，主机，宿主机
  • hosting，托管
  • idempotent，幂等的
  • image，镜像
  • image registry，镜像仓库
  • ingress，入站
  • init container，Init 容器
  • key
    • 在加密解密、安全认证上下文中，译为密钥
    • 在配置文件、数据结构上下文中，译为主键，或键
  • label，标签
  • label selector，标签选择算符
  • lifecycle，生命周期
  • limit，限制，限值
  • liveness probe，存活态探针
  • load balance，负载均衡
  • load balancer，负载均衡器
  • log flush，清刷日志数据
  • loopback，本地回路
  • manifest，清单，清单文件
  • master node，主控节点
  • metric
    • 用来指代被测量的数据源时，译为指标
    • 用来指代测量观测结果时，译为度量值
  • mount，挂载
  • namespace，名字空间，命名空间
  • orphans，孤立或孤立的
  • override，覆写
  • owner，所有者，属主
  • pending，悬决的
  • persistent volume，持久卷
  • persistent volume claim，持久卷申领
  • pipeline，流水线
  • prerequisites，依赖，前提条件（根据上下文判断）
  • priority class，优先级类
  • probe，探针
  • provision，供应
  • pull，拉取
  • push，推送
  • quota，配额
  • readiness probe，就绪态探针
  • replica，副本
  • repo，仓库
  • repository，仓库
  • revision，修订版本
  • role，角色
  • role binding，角色绑定
  • rolling update，滚动更新
  • rollout，上线
  • rotate，轮换
  • round robin，轮转
  • runtime，运行时
  • scale in/out，横向缩容/扩容
  • scale up/down，纵向扩容/缩容
  • scale
    • 做动词用时，译为“扩缩”，或者“改变…的规模”
    • 做名词用时，译为“规模”
  • scheduler，调度器
  • service，服务
  • service account，服务账号
  • service account token，服务账号令牌
  • service discovery，服务发现
  • service mesh，服务网格
  • session，会话
  • sidecar，挂斗
  • skew，偏移
  • spec，规约
  • specification，规约
  • startup probe，启动探针
  • stateless，无状态的
  • static pod，静态 Pod
  • stderr，标准错误输出
  • stdin，标准输入
  • stdout，标准输出
  • storage class，存储类
  • taint，污点
  • threshold，阈值
  • toleration，容忍度
  • topology，拓扑
  • topology spread constraint，拓扑分布约束
  • traffic，流量
    • 在某些上下文中，可以根据情况译为“服务请求”，“服务响应”
  • unmount，卸载
  • use case，用例，使用场景
  • volume，卷
  • worker node，工作节点
  • workload，工作负载