--- title: 中文本地化样式指南 content_type: concept --- 本节详述文档中文本地化过程中须注意的事项。 这里列举的内容包含了**中文本地化小组**早期给出的指导性建议和后续实践过程中积累的经验。 在阅读、贡献、评阅中文本地化文档的过程中，如果对本文的指南有任何改进建议， 都请直接提出 PR。我们欢迎任何形式的补充和更正！ ## 一般规定 {#general} 本节列举一些译文中常见问题和约定。 ### 英文原文的保留 {#commented-en-text} 为便于译文审查和变更追踪，所有中文本地化 Markdown 文件中都应使用 HTML 注释 `` 将英文原文逐段注释起来，后跟对应中文译文。例如： ``` 中文译文对应 ... ``` 不建议采用下面的方式注释英文段落，除非英文段落非常非常短： ``` 中文译文对应 ... ``` 无论英文原文或者中文译文中，都不要保留过多的、不必要的空白行。 #### 段落划分 {#paras} 请避免大段大段地注释和翻译。一般而言，每段翻译可对应两三个自然段。 段落过长会导致译文很难评阅。但也不必每个段落都单独翻译。例如： ``` ## 概述 {#overview} ### 概念 {#concept} 第一段落，不太长。 ``` 以下风格是不必要的： ``` ## 概述 {#overview} ### 概念 {#concept} 第一段落，不太长。 ``` #### 编号列表的处理 {#list} 编号列表需要编号的连续性，处理不好的话可能导致输出结果错误。 由于有些列表可能很长，一次性等将整个列表注释掉再翻译也不现实。 推荐采用下面的方式。 假定英文为： ``` 1. Prepare something 1. Followed by a long step with code snippets and notes ... this is a really long item 1. Another long item ... .. continues here 1. Almost done ... ``` 本地化处理： ``` 1. 准备工作，... 这里每行缩进 3 个空格 2. 这里是第二个编号，但需要显式给出数字，不能沿用英文编号。 缩进内容同上，3 个空格。 即使有三个反引号的代码段或者短代码，都按 3 个空格缩进。 3. 继续列表。 如果条目有多个段落，也要 保持缩进对齐以确保排版正确。 4. 列表终于结束 ``` #### Frontmatter 的处理 {#frontmatter} 页面中的 Frontmatter 指的是文件头的两个 `---` 中间的部分。 对这一部分，解析器有特殊处理，因此不能将英文部分放在前面，中文跟在后面。 需要将二者顺序颠倒。如下所示： ``` --- title: 译文标题 type: concept weight: 30 --- ``` 这里要注意的是： - `title`、`description` 的内容要翻译，其他字段一般不必（甚至不可）翻译。 - `reviewers` 部分要删除，不然中文译文会转给英文作者来审阅。 #### 短代码（shortcode）处理 {#shortcode} 通过 HTML 注释的短代码仍会被运行，因此需要额外小心。建议处理方式： ``` {{}} 中文译文 {{}} ``` {{< note >}} 现行风格与之前风格有些不同，这是因为较新的 Hugo 版本已经能够正确处理短代码中的注释段落。 保持注释掉的英文与译文都在短代码内更便于维护。 {{< /note >}} ### 博客译者署名 {#blog-translators-signature} 翻译一篇博客需要花费大量的时间和精力，添加署名是对译者工作的认可， 也有利于激励贡献者同步英文博客，提升博客质量。 如要添加译者署名，可在作者下面一行添加译者相关内容。例如： ``` **作者** ：Alice (Google) **译者** ：李明 (百度) ``` {{< note >}} 译者也可以放弃署名，这取决于个人偏好，不是强制性的。 译者所属公司由译者本人决定是否填写。 多人翻译同一篇博客默认按照译者的贡献大小进行署名，贡献越大的署名越靠前。 {{< /note >}} ### 译与不译 {#keep-or-translate} #### 资源名称或字段不译 {#resource-name-or-fields} 根据英文原文写作风格约定【也在持续修订改进】，对 Kubernetes 中的 API 资源均按其规范中所给的大小写形式书写，例如：英文中会使用 Deployment 而不是 deployment 来表示名为 "Deployment" 的 API 资源类型和对象实例。 对这类词语，一般不应翻译。 {{< note >}} 英文原文在这方面并不严谨，译者或中文译文的评阅者要非常留心。 比如 Secret 资源，很多时候被误写为 secret。 这时在本地化版本中一定不能译为“秘密”，以免与原文的语义不符。 {{< /note >}} #### 代码中的注释 {#code-comments} 一般而言，代码中的注释需要翻译，包括存放在 `content/zh-cn/examples/` 目录下的清单文件中的注释。 #### 出站链接 {#external-links} 如果超级链接的目标是 Kubernetes 网站之外的纯英文网页，链接中的内容**可以**不翻译。 例如： ``` 请参阅 [installation caveats](https://acme.com/docs/v1/caveats) ... ``` {{< note >}} 注意，这里的 `installation` 与 `参阅` 之间留白，因为解析后属于中英文混排的情况。 {{< /note >}} ### 标点符号 {#punctuations} 1. 译文中标点符号要使用全角字符，除非以下两种情况： - 标点符号是英文命令的一部分； - 标点符号是 Markdown 语法的一部分。 1. 英文排比句式中采用的逗号，在译文中要使用顿号代替，以便符合中文书写习惯。 ## 更新译文 {#update} 由于整个文档站点会随着 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` 上次提交以来发生的所有变更，可使用： ``` ./scripts/lsync.sh content/zh-cn/docs/foo/bar.md ``` ## 关于链接 {#about-links} ### 链接锚点 {#anchors} 英文 Markdown 中的各级标题会自动生成锚点，以便从其他页面中链接。 在译为中文后，相应的链接必然会失效。为防止这类问题， 建议在翻译各级标题时，使用英文方式显式给出链接锚点。例如： ``` ### 创建 Pod {#create-a-pod} ``` 此类问题对于概念部分的页面最为突出，需要格外注意。 ### 中文链接目标 {#link-to-zh-pages} 由于大部分页面已经完成中文本地化，这意味着很多链接可以使用中文版本作为目标。 例如： ``` 更多的信息可参考[卷](/zh-cn/docs/concepts/storage/)页面。 ``` 如果对应目标页面尚未本地化，建议登记一个 Issue。 {{< note >}} Website 的仓库中 `scripts/linkchecker.py` 是一个工具，可用来检查页面中的链接。 例如，下面的命令检查中文本地化目录 `/content/zh-cn/docs/concepts/containers/` 中所有 Markdown 文件中的链接合法性： ```shell ./scripts/linkchecker.py -l zh-cn -f /docs/concepts/containers/**/*.md ``` {{< /note >}} ## 排版格式 {#layout-format} 以下为译文 Markdown 排版格式要求： - 中英文之间留一个空格 * 这里的“英文”包括以英文呈现的超级链接 * 这里的中文、英文都**不包括**标点符号 - 译文 Markdown 中不要使用长行，应适当断行。 * 可根据需要在 80-120 列断行 * 最好结合句子的边界断行，即一句话在一行，不必留几个字转到下一行 * 不要在两个中文字符中间断行，因为这样会造成中文字符中间显示一个多余空格， 如果句子太长，可以从中文与非中文符号之间断行 * 超级链接文字一般较长，可独立成行 - 英文原文中可能通过 `_text_` 或者 `*text*` 的形式用斜体突出部分字句。 考虑到中文斜体字非常不美观，在译文中应改为 `**译文**` 形式， 即用双引号语法生成加粗字句，实现突出显示效果。 {{< warning >}} 我们注意到有些贡献者可能使用了某种自动化工具，在 Markdown 英文原文中自动添加空格。 虽然这些工具可一定程度提高效率，仍然需要提请作者注意，某些工具所作的转换可能是不对的， 例如将 `foo=bar` 转换为 `foo = bar`、将 `），另一些文字` 转换为 `） ，另一些文字` 等等， 甚至将超级链接中的半角井号（`#`）转换为全角，导致链接失效。 {{< /warning >}} ## 特殊词汇 {#special-words} 英文中 "you" 翻译成 "你"，不必翻译为 "您" 以表现尊敬或谦卑。 ### 术语拼写 {#terms-spelling} 按中文译文习惯，尽量不要在中文译文中使用首字母小写的拼写。例如： ``` 列举所有 pods，查看其创建时间 ... [No] 列举所有 Pod，查看其创建时间 ... [Yes] ``` **第一次**使用首字母缩写时，应标注其全称和中文译文。例如： ``` 你可以创建一个 Pod 干扰预算（Pod Disruption Budget，PDB）来解决这一问题。 所谓 PDB 实际上是 ... ``` 对于某些特定于 Kubernetes 语境的术语，也应在**第一次**出现在页面中时给出其英文原文， 以便读者对照阅读。例如： ``` 镜像策略（Image Policy）用来控制集群可拉取的镜像仓库（Image Registry）源。 ``` ### 术语对照 {#glossary} 本节列举常见术语的统一译法。除极个别情况，对于专业术语应使用本节所列举的译法： - API Server，API 服务器 - GA (general availability)，正式发布 - addons，插件 - admission controller，准入控制器 - affinity，亲和性 - annotation，注解 - anti-affinity，反亲和性 - attach，挂接 - authenticate，身份验证 - authorize，授权或鉴权 - 将权限授予某主体时，译为“授权” - 根据某些参数/条件来确定具有哪些权限时，译为“鉴权” - authorizer，鉴权器 - autoscale，自动扩缩容 - bearer token，持有者令牌 - capabilities * 当泛指某主体执行某操作的能力时，可直译为“能力” * 当特指 Linux 操作系统上的[权限控制](http://man7.org/linux/man-pages/man7/capabilities.7.html)机制时，译为“权能字” - 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，工作负载