https://github.com/servicemesher/istio-official-translation

Istio官网中文本地化
https://github.com/servicemesher/istio-official-translation

docs istio service-mesh

Last synced: 4 days ago
JSON representation

Istio官网中文本地化

• Host: GitHub
• URL: https://github.com/servicemesher/istio-official-translation
• Owner: servicemesher
• Created: 2018-06-27T06:34:39.000Z (over 6 years ago)
• Default Branch: master
• Last Pushed: 2020-08-26T10:00:20.000Z (about 4 years ago)
• Last Synced: 2024-11-04T15:50:59.960Z (12 days ago)
• Topics: docs, istio, service-mesh
• Homepage: https://www.servicemesher.com/istio-trans/
• Size: 365 KB
• Stars: 228
• Watchers: 29
• Forks: 45
• Open Issues: 148
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
# Istio 官方文档翻译指导手册

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

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

## 基本流程

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

- 任务领取：在本仓库的 Issue 页面领取待翻译的任务；

- 翻译：根据任务提示进行翻译工作；

- 提交：翻译人员提交 PR 等待 review；

- 校对：其他翻译人员对当前任务进行 review；

- 终审：管理员团队对翻译内容进行最后确认；

- 预览：和源文档进行比对，查看显示效果；

- 合并：merge 进入官方仓库，任务结束。

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

## 翻译指南

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

### 准备工作

- 账号：您需要先准备一个钉钉号和 GitHub 账号。钉钉用来协作和沟通，Github 进行任务认领和翻译提交。

- 申请加入：请扫描下面的二维码加入钉钉协作群，通过审批后您需要登记一下基本信息（具体见群公告），之后管理员会将您添加到 ServiceMesher 的 GitHub 组织，即可正式参与翻译。

  ![dingding](https://tva1.sinaimg.cn/large/006y8mN6ly1g8ffa1lksfj306b08cgm4.jpg)

- 为保证翻译的统一性和准确性，请在翻译前仔细阅读[术语表](term.md)

  - 常用词汇：对常见的技术词汇给出统一的翻译；

  - 术语：文档中出现的专有技术名词，关键词，**保持原文不翻译；**

- 仓库和分支管理

  - fork [官网](https://github.com/istio/istio.io)的仓库，并作为自己仓库的上游：`git remote add upstream` ；

  - 在自己的仓库，也就是 origin 上进行翻译；

  - 一个任务新建一个 branch；建议名称为：`zh-trans-`

### 翻译流程

#### Step1：任务浏览

访问[任务列表](https://github.com/servicemesher/istio-official-translation/issues)，会看到待领取任务（默认 Open 状态，label 中带有`pending`字样）。通常情况下，您只需要关心状态和优先级两个 label。

**状态 label：**

- `pending`：待领取的任务；

- `translating`：已经有人领取，正在翻译的任务；

- `pushed`：已翻译并生成 PR，正在进行 review；

- `merged`：PR 已合并，任务完成。

**优先级 label：**

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

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

可以简单的通过点击标签来进行过滤，也可以参考 [github 查询语法](https://help.github.com/articles/searching-issues-and-pull-requests/)，来完成更复杂的查询。

#### Step2：任务领取

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

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

#### Step3：翻译

- 请随时参考[翻译约定和术语表](term.md)，若对某些词汇的翻译模棱两可，可以直接回复该 Issue，或者在钉钉群请求帮助。

- 文档由若干 `md` 和 `html` 文档构成，将 issue 中给出的原始文件复制一份到对应中文目录下进行翻译。

- 译文中的英文与中文建议用空格分隔, 可以使用这个[自动化中英文格式化 md 的软件](https://pypi.org/project/zhlint/)。

- 锚点：所有的标题都要补充英文锚点，如英文标题为`What is a service mesh?`，则中文翻译的标题应该为`服务网格是什么？{#what-is-a-service-mesh}`。锚点默认所有英文单词均小写，可以在  对应的页面找到英文锚点并添加。但因为专有名词等原因，在使用`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，可以去[这里](https://gohugo.io/getting-started/quick-start/)查看如何安装。

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

```text

                   | 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 后，运行下面的命令下载镜像：

```bash

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

```

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

```bash

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 仓库的根目录](https://github.com/istio/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](https://github.com/istio/istio.github.io/pulls)，PR 被合并后就可以通过 [Istio 网站预览页面](https://preliminary.istio.io/zh/)看到被合并后的页面。为方便管理和辨识，请遵守下面的模板定义您的 PR：

```text

标题：

zh-translation:

内容：

ref: https://github.com/servicemesher/istio-official-translation/issues/

[ ] 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：

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

- 初审：负责对翻译的内容和原文较为精细的进行对比，保证语句通顺，无明显翻译错误；

- 终审：负责对翻译的文档做概要性的检查，聚焦在行文的通顺性、一致性、符合中文语言习惯，词汇、术语准确。终审通过后由管理员 approve 当前 PR，就可以进行合并了。

**参与 Review**：所有 istio.io 的 PR 都会通过 Github 机器人同步在钉钉群里，如果看到感兴趣的 PR 就在[本项目](https://github.com/servicemesher/istio-official-translation)中对应的 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

术语、词汇翻译问题回复[这里](https://github.com/servicemesher/istio-official-translation/issues/77)。

CI 报错等其他问题回复[这里](https://github.com/servicemesher/istio-official-translation/issues/1445)。

#### 有哪些修改 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 [网站仓库的根目录](https://github.com/istio/istio.io)运行`make serve`启动，如果您的网络环境无法访问此资源，请使用`make serve IMG=jimmysong/istio-testing-build-tools:2019-10-24T14-05-17`命令，启动时 docker 镜像会在项目目录中生成`generated`、`tmp`和`resources`静态资源目录。

3. 在初次生成静态资源目录后，就可以正常使用`hugo server`来启动项目了。

#### 文档更新了怎么办？

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

#### 定义的锚点报拼写错误

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

![anchor err](https://user-images.githubusercontent.com/36752240/68187530-e0750280-ffe1-11e9-8878-887f1d0c03ca.png)

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

#### CI deploy/netlify 报错

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

```bash

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](https://github.com/istio/istio.io/pull/5379)，已经解决。

#### 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 微信公众号二维码](https://tva1.sinaimg.cn/large/006y8mN6gy1g872im58vmj312m0begp8.jpg)