README.zh-CN.md

vertx 4的官网翻译项目

本地运行

本项目运行环境为node 16, python 2.7

翻译说明

如何认领

Issues 里面带 待认领 标签的都是 需要翻译的文档。

请在想翻译的文档对应 issue 下面留言认领，我们会Assign给你，并修改issue标签等。

翻译注意事项

请 Fork 本项目再进行翻译。

除文档外，其他翻译直接翻译项目内的文件。

文档翻译需要翻译的是 docs/translation 目录。翻译完一个模块后，请在 docs/metadata/*.jsx 中搜索对应模块的简介并翻译（对应文档首页的简介）。

翻译原则上，建议中文段落和英文段落行数一致，这样在合并英文版本时，可以更清晰的发现文档中的冲突并解决。

目录的跳转是根据锚点来实现，但中文的标题处理的锚点似乎有问题，因此建议给所有标题添加上锚点，使页内跳转能正常运行。示例：

[[id]]
# 标题

使用<<id, 标题>>可以跳转到上面的标题处，其中id是锚点的id，“标题” 则是显示的内容。

英文文档里省略了id，直接使用了英文标题，但翻译成中文后，<<标题>> 中的中文标准就定位不了。因此需要按上述示例中那样来 精确定位。同时，为了确保中英文一致，建议这里的id使用官网上的id，具体方法就是点击官网上（或者在未翻译时在本地执行）的链接跳转后 使用地址栏#后面的内容，比如上面的示例，在地址栏中的链接应该是 http://localhost:3000/docs/xxx/#id

如果是通过 npm run dev 来预览的话，翻译完成后，刷新即可看到翻译后的文档。

新版本是预编译*.adoc文件的，因此翻译完成后，本地预览需要执行 npm run update-docs。

新版本翻译在各版本目录下增加了 .cache.version 文件来控制缓存，修改完翻译后，修改此文件可以破坏缓存，从而让翻译的文件重新编译。

网络不好的情况下，可以修改 download.js 第 10 行 repoUrl 为阿里云（其他也可以）的镜像地址：https://maven.aliyun.com/repository/central

因为是以 index.adoc 文件来计算缓存的key，非 index.adoc 文件翻译后，如果不修改 index.adoc 文件，则不会更新缓存，页面也不会更新，需要在 index.adoc中进行小的修改

如何提交

提交翻译通过PR（Pull Request）进行。请在自己Fork的项目中发起PR，而不是本项目（本项目Fork了官方项目，若在本项目发起PR，默认会提交到官方项目）。

PR的描述中请注明对应的issue ID，如： 完成 #23 翻译。

提交PR后，我们会分配 Reviewer； Review 文档给出的建议，可以:

1. 直接在github页面对应修改意见里点击 Commit Suggestion 按钮直接提交；
2. 在github页面对应修改意见里点击 Batch suggestion to batch，接受多个修改意见后，在上方的 Commit suggestions 统一提交；
3. 也可以自己在本地修改后直接提交，然后在github页面对应修改意见里面点击 Resolve Conversation。

如何 Review

分配Reviewer后Github会发送邮件，也可以主动到 PR 列表里找感兴趣的文档协助Review。

在具体PR页面里，点击 Files changed 标签页可以看到该PR的修改内容。在有修改意见或疑问的行，点击左边的加号，可以评论，或加入修改意见（点击 Insert a suggestion 按钮）。

review完毕后，点击左上角 Review changes，有三个选项：

• Comment ： 只提交评论
• Approve : 觉得PR没问题，同意修改内容
• Request Change : 觉得PR还需要进一步修改

分支说明

翻译只翻译master分支，因为创建的其他分支最终需要合并到master分支。

english分支与master分支的区别是：english 分支 的 translation目录为当前版本的英文文档。主要是版本升级时，更新英文文档时用。

版本更新操作说明

当vert.x发布新的版本，english分支需要更新为最新英文文档，而master分支需要将当前文档复制一份到 docs/translation/x.x.x 目录 中去，其中 x.x.x 为当前文档的版本。然后合并english分支到当前分支，并解决相应冲突。解决的方案如下

1. 英文删除的。对应的翻译也删除（如果遵守了前面提到的英文行数和中文行数对应的话，应该比较好找到）
2. 英文增加。因为没有翻译，所以保留英文部分，或者可以安排人立即翻译
3. 英文修改。TODO 此处需要讨论之后定

english分支更新文档可合并 https://github.com/vertx-web-site/vertx-web-site 项目后，执行下面脚本来更新。

npm run copy-english

执行本命令前，请确保已经执行 npm run update-docs 更新了文档