Skip to content
This repository has been archived by the owner on Aug 8, 2022. It is now read-only.

协作指南

Jinjiang edited this page Sep 19, 2021 · 4 revisions

欢迎参与 Vue 3,以下内容适用于参与 vuejs/docs-next-zh-cn 仓库的协作,在此之前,你应该阅读过术语翻译约定

1. 开始参与

2. 开发

$ git clone https://github.com/vuejs/docs-next-zh-cn.git # clone 仓库
$ npm install # 安装依赖 (或yarn,国内用户可使用 [cnpm](https://cnpmjs.org/))
$ npm run serve # 启动开发环境,本地访问(http://localhost:8080)

在完成翻译后,发起 PR 即可,review 无误后,将合并入主仓库,访问域名:https://v3.cn.vuejs.org 即可看到效果

2.1 commit message 规范

具体规范参考

建议 message 使用英文,关键词后加英文冒号,再加空格,一段话描述,如:

  • style: fix the strong style for Chinese characters
  • chore: update yarn.lock
  • review: introduction

2.2 Pull Request 标题规范

具体参考旧 PR 建议标题使用英文,你可以在描述里使用中文描述详细的特性。

3. 参与贡献

3.1 翻译和校对

  • 绝大部分的翻译和校对工作已在网站初期集中进行并完成

    可以认领自己想要翻译或校对的页面,并在完成后提交 + 创建 PR。

    详见 https://github.com/vuejs/docs-next-zh-cn/issues/18

    在长期和英文站保持同步的过程中,我们的文档可能会偶尔存在暂时未翻译的段落,这些段落通常都以 <!-- TODO: translation --> 开头作为标记。所以欢迎大家在源码中搜索这些段落并贡献翻译。你也可以通过这个链接快速找到尚未翻译好的内容。

3.2 除了翻译和校对

  • 定期同步最新的翻译等网站改动:可以直接发起 PR,具体操作推荐参考常见问题中的相应描述
  • 非文档内容的代码同步:涉及比较细节的仓库结构和实现,一般会由团队自行发起 PR 并完成
  • 网络环境和本地化:如果发现任何这方面的问题可以直接发起 issue 讨论
  • 翻译讨论:可以随时发起 issue 讨论

3.3 哪些讨论建议去英文版讨论

  • 对于原文内容的讨论,而非中文译法本身
  • 对于网站代码的优化,除非是特别针对中文站或国内环境的

3.4 哪些讨论原则上这里不受理

  • 对于 Vue 的使用答疑,请移步到各大技术社区讨论

4. 注意事项

  • 尽量保持原文的编码风格,不产生不必要的格式变化和改动。如果对格式有异议,建议直接在英文站讨论。
  • 我们有一个实验性的中文格式工具:zhlint 来检测中文格式,详见 6.1 如何使用 zhlint
  • 同步最新的翻译时,建议在发起 PR 时备注当时英文版最新的 commit hash。

5. 常见问题

  1. 发现有些段落翻译晦涩难懂?

    在搜索未得到相关讨论结果后,可发起 issue,有结论后,我们定期汇总至术语翻译约定 wiki

  2. 如何发起 Pull Requests?

    • Clone 仓库 image
    • 更改完毕后,推送到自己的仓库
    • 比较仓库,右侧为你的仓库和分支,左侧是需要并入的目标仓库和分支 image
    • 选择比较的分支后,点击按钮:“Create pull request” 即可发起
  3. 如何定期同步最新的翻译等网站改动

    • 你首先可以参考项目组之前完成过的记录
    • 然后通过 GitHub compare view 功能快速查阅尚未同步的英文站近期新的改动,你也可以利用我们在仓库里提供的 sync 脚本 (npm run syncyarn sync) 来查阅。
    • 最后创建对应的 PR 并完成代码同步和翻译同步
    • 对于大块的新的英文内容,可以选择暂时不翻译,但就近加入注释 <!-- TODO: translation --> 方便大家后续搜索并认领。
  4. 如何查看“我的贡献”?

  5. 如果有一个章节很长,我只翻译了一半,后续不想翻译了?

    • 虽然允许,但,我们还是建议你,最好以一个 .md 文件为单位来发起 PR,避免后续来回追踪。

6. 其它

6.1 如何使用 zhlint

  • 安装 zhlint

    npm install zhlint -g # 或 yarn global add zhlint
  • 使用 zhlint 查看

    zhlint readme.md # 查看 `zhlint` 检测的结果
  • 使用 zhlint 修复

    zhlint readme.md --fix # 使用 `zhlint` 修复