From 2db6b9a08733abe37b84309658f936f52c7c8bf9 Mon Sep 17 00:00:00 2001 From: Qiming Teng Date: Wed, 30 Sep 2020 14:49:38 +0800 Subject: [PATCH] [zh] Add style guide for Chinese localization Most of the contents are summarized from previous practices. This PR is an attempt to document these practices as guidelines. --- content/zh/docs/contribute/localization.md | 2 +- content/zh/docs/contribute/localization_zh.md | 465 ++++++++++++++++++ 2 files changed, 466 insertions(+), 1 deletion(-) create mode 100644 content/zh/docs/contribute/localization_zh.md diff --git a/content/zh/docs/contribute/localization.md b/content/zh/docs/contribute/localization.md index 3f6788a806..5ad2b88a87 100644 --- a/content/zh/docs/contribute/localization.md +++ b/content/zh/docs/contribute/localization.md @@ -455,7 +455,7 @@ Some language teams have their own language-specific style guide and glossary. F ### 特定语言的样式指南和词汇表 一些语言团队有自己的特定语言样式指南和词汇表。 -例如，请参见[韩语本地化指南](/ko/docs/contribute/localization_ko/)。 +例如，请参见[中文本地化指南](/zh/docs/contribute/localization_zh/)。 + +本节详述文档中文本地化过程中须注意的事项。 +这里列举的内容包含了*中文本地化小组*早期给出的指导性建议和后续实践过程中 +积累的经验。 +在阅读、贡献、评阅中文本地化文档的过程中，如果对本文的指南有任何改进建议， +都请直接提出 PR。我们欢迎任何形式的补充和更正！ + + + +## 一般规定 + +本节列举一些译文中常见问题和约定。 + +### 英文原文的保留 + +为便于译文审查和变更追踪，所有中文本地化 Markdown 文件中都应使用 HTML 注释 +`` 将英文原文逐段注释起来，后跟对应中文译文。例如： + +``` + +中文译文对应 ... +``` + +不建议采用下面的方式注释英文段落，除非英文段落非常非常短： + +``` + +中文译文对应 ... + +``` + +无论英文原文或者中文译文中，都不要保留过多的、不必要的空白行。 + +#### 段落划分 + +请避免大段大段地注释和翻译。一般而言，每段翻译可对应两三个自然段。 +段落过长会导致译文很难评阅。但也不必每个段落都单独翻译。例如： + +``` + +## 概述 {#overview} + +### 概念 {#concept} + +第一段落，不太长。 +``` + +以下风格是不必要的： + +``` + +## 概述 {#overview} + + +### 概念 {#concept} + + +第一段落，不太长。 +``` + +#### 编号列表的处理 + +编号列表需要编号的连续性，处理不好的话可能导致输出结果错误。 +由于有些列表可能很长，一次性等将整个列表注释掉再翻译也不现实。 +推荐采用下面的方式。 + +假定英文为： + +``` +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 指的是文件头的两个 `---` 中间的部分。 +对这一部分，解析器有特殊处理，因此不能将英文部分放在前面，中文跟在后面。 +需要将二者顺序颠倒。如下所示： + +``` +--- +title: 译文标题 +type: concept +weight: 30 +--- + + +``` + +这里要注意的是： + +- `title`、`description` 的内容要翻译，其他字段一般不必（甚至不可）翻译。 +- `reviewers` 部分要删除，不然中文译文会转给英文作者来审阅。 + + +#### 短代码（shortcode）处理 + +通过 HTML 注释的短代码仍会被运行，因此需要额外小心。建议处理方式： + +``` + +{{}} +中文译文 +{{}} +``` + +评阅人应该不难理解中英文段落的对应关系。但是如果采用下面的方式，则会出现 +两个 `note`，因此需要避免。这是因为被注释起来的短代码仍会起作用！ + +``` + +{{}} +中文译文 +{{}} +``` + +### 译与不译 + +#### 资源名称或字段不译 + +根据英文原文写作风格约定【也在持续修订改进】，对 Kubernetes 中的 API +资源均按其规范中所给的大小写形式书写，例如：英文中会使用 Deployment 而不是 +deployment 来表示名为 "Deployment" 的 API 资源类型和对象实例。 + +对这类词语，一般不应翻译。 + +{{< note >}} +英文原文在这方面并不严谨，译者或中文译文的评阅者要非常留心。 +比如 Secret 资源，很多时候被误写为 secret。这时在本地化版本中一定 +不能译为“秘密”，以免与原文的语义不符。 +{{< /note >}} + +#### 代码中的注释 + +一般而言，代码中的注释需要翻译，包括存放在 `content/zh/examples/` 目录下 +的清单文件中的注释。 + + +#### 出站链接 + +如果超级链接的目标是 Kubernetes 网站之外的纯英文网页，链接中的内容*可以*不翻译。 +例如： + +``` + +请参阅 [installation caveats](https://acme.com/docs/v1/caveats) ... +``` + +注意，这里的 `installation` 与 `参阅` 之间留白，因为解析后属于中英文混排的情况。 + +### 标点符号 + +译文中标点符号要使用全角字符，除非以下两种情况： + +- 标点符号是英文命令的一部分； +- 标点符号是 Markdown 语法的一部分。 + +英文排比句式中采用的逗号，在译文中要使用顿号代替，复合中文书写习惯。 + +## 关于链接 + +### 链接锚点 + +英文 Markdown 中的各级标题会自动生成锚点，以便从其他页面中链接。 +在译为中文后，相应的链接必然会失效。为防止这类问题，建议在翻译 +各级标题时，使用英文方式显式给出链接锚点。例如： + +``` + +### 创建 Pod {#create-a-pod} +``` + +此类问题对于概念部分的页面最为突出，需要格外注意。 + + +### 中文链接目标 + +由于大部分页面已经完成中文本地化，这意味着很多链接可以使用中文版本作为目标。 +例如： + +``` + +更多的信息可参考[卷](/zh/docs/concepts/storage/)页面。 +``` + +如果对应目标页面尚未本地化，建议登记一个 Issue。 + +{{< note >}} +Website 的仓库中 `scripts/linkchecker.py` 是一个工具，可用来检查页面中的链接。 +例如，下面的命令检查中文本地化目录 `/content/zh/docs/concepts/containers/` +中所有 Markdown 文件中的链接合法性： + +``` +./scripts/linkchecker.py -l zh -f /docs/concepts/containers/**/*.md +``` +{{< /note >}} + +## 排版格式 + +以下为译文 Markdown 排版格式要求： + +- 中英文之间留一个空格 + * 这里的“英文”包括以英文呈现的超级链接 + * 这里的中文、英文都不包括标点符号 +- 译文 Markdown 中不要使用长行，应适当断行。 + * 可根据需要在 80-120 列断行 + * 最好结合句子的边界断行，即一句话在一行，不必留几个字转到下一行 + * 超级链接文字一般较长，可独立成行 + +{{< warning >}} +我们注意到有些贡献者可能使用了某种自动化工具，在 Markdown 英文原文中自动 +添加空格。虽然这些工具可一定程度提高效率，仍然需要提请作者注意，某些工具 +所作的转换可能是不对的，例如将 `foo=bar` 转换为 `foo = bar`、将 +`），另一些文字` 转换为 `） ，另一些文字` 等等，甚至将超级链接中的半角 +井号（`#`）转换为全角，导致链接失效。 +{{< /warning >}} + +英文中 "you" 翻译成 "你" 不必是 “您" +文章内的链接用英文例如 (#deploying )，在对应的标题上后面加上 {#deploying} + + +## 术语 + +### 术语拼写 + +按中文译文习惯，尽量不要在中文译文中使用首字母小写的拼写。例如： + +``` +列举所有 pods，查看其创建时间 ... [No] +列举所有 Pod，查看其创建时间 ... [Yes] +``` + +*第一次*使用首字母缩写时，应标注其全称和中文译文。例如： + +``` +你可以创建一个 Pod 干扰预算（Pod Disruption Budget，PDB）来解决这一问题。 +所谓 PDB 实际上是 ... +``` + +对于某些特定于 Kubernetes 语境的术语，也应在*第一次*出现在页面中时给出其英文原文， +以便读者对照阅读。例如： + +``` +镜像策略（Image Policy）用来控制集群可拉取的镜像仓库（Image Registry）源。 +``` + +### 术语对照 + +本节列举常见术语的统一译法。除极个别情况，对于专业术语应使用本节所列举的译法： + +- API Server，API 服务器 +- GA (general availability)，正式发布 +- addons，插件 +- admission controller，准入控制器 +- affinity，亲和性 +- annotation，注解 +- anti-affinity，反亲和性 +- attach，挂接 +- 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，工作负载