search

servicemesher / istio-official-translation

Istio官网中文本地化
https://www.servicemesher.com/istio-trans/
228 stars 45 forks source link
docs istio service-mesh

readme

Istio 官方文档翻译指导手册

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

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

基本流程

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

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

翻译指南

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

准备工作

翻译流程

Step1：任务浏览

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

状态 label：

优先级 label：

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

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

Step2：任务领取

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

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

Step3：翻译

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

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

Step6：校对（review）

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

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

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

Review 的基本流程

Step7：任务完成

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

FAQ

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

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

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

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

  1. /accept: 适用于 pending 状态，且当前无人指派的 Issue，输入该指令，会将该 Issue 指派给当前用户。并变更状态为 translating
  2. /pushed: 适用于 translating 状态的 Issue，输入该指令，会将该 Issue 指派给当前用户。并变更状态为 pushed
  3. /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.

解决方法：

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

文档更新了怎么办？

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

定义的锚点报拼写错误

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

anchor err

主要的原因是在对于这些专有名词在.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 微信公众号二维码