Istio 官方文档翻译指导手册

2018 年我们社区组织翻译了 Istio 官网文档的 1.2 版本（已归档于：https://archive.istio.io/v1.2/zh/），随着 Istio 版本的快速迭代，老版本有许多需要更新的地方。为了让国内对 Istio 感兴趣的工程师可以学习到最新的官方文档，我们打算重启翻译工作，并基于官方的主线分支进行翻译，保证每次 Istio 在发布新版本时，同步的发布中文文档。

感谢您加入我们的翻译团队，并为 Istio 的中文化工作作出贡献。本篇文档是帮助您进行高效翻译的指导手册，建议您在正式翻译前认真阅读。

基本流程

整个翻译的基本流程包括下面几个步骤：

任务领取：在本仓库的 Issue 页面领取待翻译的任务；
翻译：根据任务提示进行翻译工作；
提交：翻译人员提交 PR 等待 review；
校对：其他翻译人员对当前任务进行 review；
终审：管理员团队对翻译内容进行最后确认；
预览：和源文档进行比对，查看显示效果；
合并：merge 进入官方仓库，任务结束。

我们通过校对、终审两轮 review 保证翻译的质量；通过预览保证显示的准确性。翻译人员在整个流程中需要做的是领取任务，翻译，提交 PR，预览自查这几步。

翻译指南

下面具体介绍一下如何进行翻译工作。

准备工作

账号：您需要先准备一个钉钉号和 GitHub 账号。钉钉用来协作和沟通，Github 进行任务认领和翻译提交。
申请加入：请扫描下面的二维码加入钉钉协作群，通过审批后您需要登记一下基本信息（具体见群公告），之后管理员会将您添加到 ServiceMesher 的 GitHub 组织，即可正式参与翻译。
为保证翻译的统一性和准确性，请在翻译前仔细阅读术语表
- 常用词汇：对常见的技术词汇给出统一的翻译；
- 术语：文档中出现的专有技术名词，关键词，保持原文不翻译；
仓库和分支管理
- fork 官网的仓库，并作为自己仓库的上游：git remote add upstream ；
- 在自己的仓库，也就是 origin 上进行翻译；
- 一个任务新建一个 branch；建议名称为：zh-trans-<isssueID>

翻译流程

Step1：任务浏览

访问任务列表，会看到待领取任务（默认 Open 状态，label 中带有pending字样）。通常情况下，您只需要关心状态和优先级两个 label。

状态 label：

pending：待领取的任务；
translating：已经有人领取，正在翻译的任务；
pushed：已翻译并生成 PR，正在进行 review；
merged：PR 已合并，任务完成。

优先级 label：

优先级从高到低分别为 priority/P0 ~ priority/P3。优先选择优先级高的进行翻译。

除此以外，我们还设置了版本号、中文标示和类型等标签。

可以简单的通过点击标签来进行过滤，也可以参考 github 查询语法，来完成更复杂的查询。

Step2：任务领取

找到未经认领的任务（pending 状态），在 issue 中回复 /accept 可以领取任务，Bot 会将任务分配给你，并修改状态为 translating。

注意：为保证质量，同一译者只能拥有三个 translating 状态的 Issue，超过数量无法继续认领。

Step3：翻译

请随时参考翻译约定和术语表，若对某些词汇的翻译模棱两可，可以直接回复该 Issue，或者在钉钉群请求帮助。
文档由若干 md 和 html 文档构成，将 issue 中给出的原始文件复制一份到对应中文目录下进行翻译。
译文中的英文与中文建议用空格分隔, 可以使用这个自动化中英文格式化 md 的软件。
锚点：所有的标题都要补充英文锚点，如英文标题为What is a service mesh?，则中文翻译的标题应该为服务网格是什么？{#what-is-a-service-mesh}。锚点默认所有英文单词均小写，可以在 https://istio.io 对应的页面找到英文锚点并添加。但因为专有名词等原因，在使用make lint检查时，和英文页面一致的锚点会报错，可根据下面的规则进行修改：
- 锚点以专有名词开头，都需要大写，比如{#Istio...}
- 打开 repo 根目录下 .spelling 文件，查找报错的锚点是否有定义。如果存在，直接使用文件中定义的形式即可（通常是大小写不同）；
- 如果不存在，通常是由几个单词组合而成，将这几个词分别在 .spelling文件中查找对应的定义，并替换；并且在他们中间添加连字符-。例如：{#Istio-CoreDNS-options}。
- 原标题中的空格以连字符-替代。
- lint 会检查锚点中的单词拼写是否正确，这就导致一些缩写不合法。这种情况下在词之间添加-即可。例如：certmanager是不合法的，需要改成{#cert-manager}
- 数字如果不在.spelling中需要更换格式
- 其他细节请参考[这里](term.md# 关于锚点)
md 代码块与代码输出内容不要翻译。
对于翻译文稿中涉及到的静态文件，直接沿用英文版的文件（例如 ! [english image](/docs/concept.....)），不再需要自行拷贝。

Step4：本地构建和预览

翻译结束后可以先在本地构建网站进行预览。有两种方式可以将 Istio 的 website 运行起来：

通过本地运行 hugo 启动

hugo 提供了一个本地的 web 服务器，可以启动网站。如果您本地没有安装 hugo，可以去这里查看如何安装。

然后，在 Istio.io 仓库的根目录下，运行hugo server在本地启动 web 服务器，通过http://localhost:1313/zh进行中文网站的预览。如看到类似下面的输出，则表示 web 服务器已经启动成功：

                   | EN  | ZH
+------------------+-----+-----+
  Pages            | 545 | 545
  Paginator pages  |   0 |   0
  Non-page files   | 164 | 164
  Static files     |  54 |  54
  Processed images |   0 |   0
  Aliases          |   1 |   0
  Sitemaps         |   2 |   1
  Cleaned          |   0 |   0

Total in 47355 ms
Watching for changes in /work/{archetypes,assets,content,data,generated,i18n,layouts,static}
Watching for config changes in /work/config.toml
Environment: "development"
Serving pages from memory
Web Server is available at http://localhost:1313/ (bind address 0.0.0.0)
Press Ctrl+C to stop

通过 Docker 启动

另外一种是直接使用 Docker 镜像启动。

在正确安装 Docker 后，运行下面的命令下载镜像：

docker pull gcr.io/istio-testing/build-tools:master-2020-08-19T17-29-34

如果您的网络环境无法访问此资源，可以执行下面的命令下载镜像的镜像：

docker pull jimmysong/istio-testing-build-tools:master-2020-08-19T17-29-34
docker tag jimmysong/istio-testing-build-tools:master-2020-08-19T17-29-34 gcr.io/istio-testing/build-tools:master-2020-08-19T17-29-34

然后在 istio.io 仓库的根目录下，执行下面的命令启动 web 服务：

make serve

启动成功后通过 http://localhost:1313/zh 进行网站的预览。

如果你想通过局域网访问该页面，可以将 Makefile.core.mk 文件中的 ISTIO_SERVE_DOMAIN ?= localhost 修改为 ISTIO_SERVE_DOMAIN ?= 局域网 IP，然后再启动 web 服务：

make serve

这可以让局域网中的其它计算机访问该页面（以及物理机访问虚拟机），注意：不要将该文件的改动提交至 PR。

启动成功后通过 http://局域网 IP:1313/zh 进行网站的预览。

Step5：提交 PR

执行make lint，初步做一下 CI 的检查，当看到有蓝色文字输出后没有报错就可以 ctrl^c 了，检查成功后再提交 PR。

可以使用 make INTERNAL_ONLY=True lint 命令，在不进行外部链接检查的情况下，完成 Lint 步骤

提交 PR

如果检查通过，就可以向 Istio 官方网站提交 PR，PR 被合并后就可以通过 Istio 网站预览页面看到被合并后的页面。为方便管理和辨识，请遵守下面的模板定义您的 PR：

标题：
zh-translation:<file_full_path>
内容：
ref: https://github.com/servicemesher/istio-official-translation/issues/<issueID>
[ ] Configuration Infrastructure
[x] Docs
[ ] Installation
[ ] Networking
[ ] Performance and Scalability
[ ] Policies and Telemetry
[ ] Security
[ ] Test and Release
[ ] User Experience
[ ] Developer Infrastructure

其中，标题中的<file_full_path>是翻译的源文件路径；内容中的 ref 是当前翻译任务的 issue 链接。

Step6：校对（review）

校对工作由没有翻译过当前文档的其他翻译人员执行，即翻译人员互为校对人员。为保证质量，我们设置了两轮 Review：

所有翻译人员互为校对人员，分配一个翻译任务同时要确定校对任务；

初审：负责对翻译的内容和原文较为精细的进行对比，保证语句通顺，无明显翻译错误；
终审：负责对翻译的文档做概要性的检查，聚焦在行文的通顺性、一致性、符合中文语言习惯，词汇、术语准确。终审通过后由管理员 approve 当前 PR，就可以进行合并了。

参与 Review：所有 istio.io 的 PR 都会通过 Github 机器人同步在钉钉群里，如果看到感兴趣的 PR 就在本项目中对应的 issue 回复一下，我们社区的 maintainer 会通过 /assign命令手动将 Review 工作指派给您。

Review 的基本流程

认领 Review：
- 新提交的 PR 每天会在协作群发布，供大家认领；
- 进入要认领的 PR，回复/review，maintainer 会将 reviewer 指派给您；
Review 重点：
- 打开 PR 提交的中文翻译，并找到对应 issue 中指定的源文件，逐段进行走查；
- 词汇检查：检查译文中出现的术语、常用词汇是否遵照了术语表的要求进行翻译；
- 格式检查：对照原文，检查译文中的标题和层次是否对应；代码块是否指定了语言；标点符号是否正确且无英文标点；超链接、图片链接是否可达；是否有错别字；
- 语句检查：分段落通读一遍，检查是否有不通顺、语病、或者不符合中文习惯的译文（啰嗦、重复、过多的助词等）
提交 comment：
- 根据发现的问题，在 PR 提交文件的对应行添加 comment，格式为原译文=>修改后译文；不确定的地方可加建议或询问，或发到协作群求助。

Step7：任务完成

通过终审后的任务会被管理员 approve，并合并到 Istio 的官方仓库中。需要您在对应的 Issue 中输入指令 /merged，Bot 会设置 Issue 的状态为 finished，并关闭 Issue。整个翻译任务就算正式完成了。您可以继续领取新的任务进行翻译，或参与校对工作。

FAQ

术语、词汇翻译问题回复这里。

CI 报错等其他问题回复这里。

有哪些修改 Issue 的自动化命令？

所有指令，都在 Issue 中以 Comment 的形式输入，仅对 Member 有效。如果出错或者不符合条件，不会有任何提示。

/accept: 适用于 pending 状态，且当前无人指派的 Issue，输入该指令，会将该 Issue 指派给当前用户。并变更状态为 translating
/pushed: 适用于 translating 状态的 Issue，输入该指令，会将该 Issue 指派给当前用户。并变更状态为 pushed
/merged: 适用于 pushed 状态的 Issue，输入该指令，会将该 Issue 指派给当前用户。并变更状态为 finished，然后关闭 Issue

初次使用 hugo 启动找不到静态资源问题：

初次使用hugo server在本地启动 web 服务，web 页面会出现如下问题，找不到静态资源。

Failed to load resource: the server responded with a status of 404 (Not Found)
Refused to apply style from 'http://localhost:1313/css/all.css' because its MIME type ('text/plain') is not a supported stylesheet MIME type, and strict MIME checking is enabled.

解决方法：

在项目根目录下执行sh scripts/build_site.sh命令，即可生成所需静态文件。但是这种方式需要安装比较多node的命令行工具，例如：sass、tsc、babel、svgstore，安装起来比较繁琐。
这里建议首次可以采用docker方式启动，参考 docker 启动教程，在 Istio 网站仓库的根目录运行make serve启动，如果您的网络环境无法访问此资源，请使用make serve IMG=jimmysong/istio-testing-build-tools:2019-10-24T14-05-17命令，启动时 docker 镜像会在项目目录中生成generated、tmp和resources静态资源目录。
在初次生成静态资源目录后，就可以正常使用hugo server来启动项目了。

文档更新了怎么办？

如果发现文档更新，并且根据文档名称在 Issue 库中找不到对应的 Issue，可以新建 Issue，Issue 标题写入变更的文件名，例如 content/docs/reference/config/policy-and-telemetry/adapters/_index.md，并在 Body 中加入 @dustise, @rootsongjc。这样就可以避免在你进行翻译的同时，Bot 重新将该文件放入任务队列。

定义的锚点报拼写错误

给标题添加的锚点完全和官方英文的一致，报类似如下错误：

主要的原因是在对于这些专有名词在.spelling文件中只定义了大写而没有定义小写导致。此时，请参考上文锚点规范书写锚点。

CI deploy/netlify 报错

本地 make serve 没问题，但官方的 deploy/netlify 报如下错误：

10:07:37 AM: added 35 packages from 9 contributors and audited 43 packages in 1.553s
10:07:37 AM: found 0 vulnerabilities
10:07:41 AM: TypeError: Cannot set property inList of [object Object] which has only a getter
10:07:41 AM:     at PluginPass.exit (/opt/build/repo/node_modules/babel-plugin-minify-simplify/lib/index.js:549:40)
10:07:41 AM:     at newFn (/opt/buildhome/.nvm/versions/node/v12.8.0/lib/node_modules/@babel/core/node_modules/@babel/traverse/lib/visitors.js:179:21)
10:07:41 AM:     at NodePath._call (/opt/buildhome/.nvm/versions/node/v12.8.0/lib/node_modules/@babel/core/node_modules/@babel/traverse/lib/path/context.js:55:20)
10:07:41 AM:     at NodePath.call (/opt/buildhome/.nvm/versions/node/v12.8.0/lib/node_modules/@babel/core/node_modules/@babel/traverse/lib/path/context.js:42:17)
10:07:41 AM:     at NodePath.visit (/opt/buildhome/.nvm/versions/node/v12.8.0/lib/node_modules/@babel/core/node_modules/@babel/traverse/lib/path/context.js:99:8)
10:07:41 AM:     at TraversalContext.visitQueue (/opt/buildhome/.nvm/versions/node/v12.8.0/lib/node_modules/@babel/core/node_modules/@babel/traverse/lib/context.js:112:16)
10:07:41 AM:     at TraversalContext.visitSingle (/opt/buildhome/.nvm/versions/node/v12.8.0/lib/node_modules/@babel/core/node_modules/@babel/traverse/lib/context.js:84:19)
10:07:41 AM:     at TraversalContext.visit (/opt/buildhome/.nvm/versions/node/v12.8.0/lib/node_modules/@babel/core/node_modules/@babel/traverse/lib/context.js:140:19)
10:07:41 AM:     at Function.traverse.node (/opt/buildhome/.nvm/versions/node/v12.8.0/lib/node_modules/@babel/core/node_modules/@babel/traverse/lib/index.js:84:17)
10:07:41 AM:     at NodePath.visit (/opt/buildhome/.nvm/versions/node/v12.8.0/lib/node_modules/@babel/core/node_modules/@babel/traverse/lib/path/context.js:97:18)
10:07:41 AM: Makefile.core.mk:49: recipe for target 'netlify' failed
10:07:41 AM: make: *** [netlify] Error 1

这是官方的一个 bug，已经解决。

CLA 检测不通过

如果你在设置 cla 之前提交了 PR，CI 里的 cla check 会失败。可以先在 PR 中回复@googlebot I signed it.。如果还失败尝试回复@googlebot I fixed it.。如果还不行，所以最好的办法是关闭当前 PR，重新用一个新的 branch 拷贝相应文件，再提交全新的 PR 即可。

ERROR: Unexpected end tag : p

如果遇到此错误，说明还没有完全修复 markdown 的 lint 问题。需要先修复完即可通过 CI 检查。

感谢

感谢您的辛勤付出！相信在大家共同的努力下 Istio 和 Service Mesh 技术会更加蓬勃的发展！

servicemesher/istio-official-translation

servicemesher

Reviews

Repository Details