中文本地化样式指南

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

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

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

    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 ...
    4. 1. Another long item ...
    5.    .. continues here
    6. 1. Almost done ...

    本地化处理：

    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. {{< note >}}
    2. <!--
    3. English text
    4. -->
    5. 中文译文
    6. {{< /note >}}

    译与不译

    资源名称或字段不译

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

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

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

    代码中的注释

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

    出站链接

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

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

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

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

      • 标点符号是 Markdown 语法的一部分。
    2. 英文排比句式中采用的逗号，在译文中要使用顿号代替，以便符合中文书写习惯。

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

    为确保准确跟踪中文化版本与英文版本之间的差异，中文内容的 PR 所包含的每个页面都必须是“最新的”。 这里的“最新”指的是对应的英文页面中的更改已全部同步到中文页面。 如果某中文 PR 中包含对 content/zh-cn/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-cn/docs/foo/bar.md

    链接锚点

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

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

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

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

    说明：

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

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

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

    • 中英文之间留一个空格

      • 这里的“英文”包括以英文呈现的超级链接
      • 这里的中文、英文都不包括标点符号

    • 译文 Markdown 中不要使用长行，应适当断行。

      • 可根据需要在 80-120 列断行
      • 最好结合句子的边界断行，即一句话在一行，不必留几个字转到下一行
      • 不要在两个中文字符中间断行，因为这样会造成中文字符中间显示一个多余空格， 如果句子太长，可以从中文与非中文符号之间断行
      • 超级链接文字一般较长，可独立成行
    • 英文原文中可能通过 _text_ 或者 *text* 的形式用斜体突出部分字句。 考虑到中文斜体字非常不美观，在译文中应改为 **译文** 形式， 即用双引号语法生成加粗字句，实现突出显示效果。

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

    英文中 “you” 翻译成 “你”，不必翻译为 “您” 以表现尊敬或谦卑。

    术语拼写

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

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

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

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

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

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

    • 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，镜像
    • 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，卷
    • workload，工作负载