Skip to content

servicemesher/istio-official-translation

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

74 Commits
 
 
 
 
 
 

Repository files navigation

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 组织,即可正式参与翻译。

    dingding

  • 为保证翻译的统一性和准确性,请在翻译前仔细阅读术语表

    • 常用词汇:对常见的技术词汇给出统一的翻译;
    • 术语:文档中出现的专有技术名词,关键词,保持原文不翻译;
  • 仓库和分支管理

    • 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,或者在钉钉群请求帮助。
  • 文档由若干 mdhtml 文档构成,将 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 有效。如果出错或者不符合条件,不会有任何提示。

  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的命令行工具,例如:sasstscbabelsvgstore,安装起来比较繁琐。
  2. 这里建议首次可以采用docker方式启动,参考 docker 启动教程,在 Istio 网站仓库的根目录运行make serve启动,如果您的网络环境无法访问此资源,请使用make serve IMG=jimmysong/istio-testing-build-tools:2019-10-24T14-05-17命令,启动时 docker 镜像会在项目目录中生成generatedtmpresources静态资源目录。
  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 微信公众号二维码