Skip to content

协作指南

Jump to bottom
Godpu edited this page Dec 10, 2022 · 19 revisions

欢迎参与 Vue 3 新版文档协作，以下内容适用于参与 vuejs-translations/docs-zh-cn 仓库的协作，在此之前，你应该阅读过翻译须知。

Vuejs-translations 组织是基于 Vue 官方筹备下围绕了 Vue 周边文档展开国际化维护的组织。

1. 开始参与

2. 开发

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

在完成翻译后，发起 PR 即可，review 无误后，将合并入主仓库，访问域名：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 翻译和校对

  • 集中翻译和校对

    目前网站还处在待翻译或待校对的状态，细则详见：https://github.com/vuejs-translations/docs-zh-cn/issues/8

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

  • 定期翻译和校对从英文站同步过来的新内容

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

3.2 除了翻译和校对

  • 定期从英文版同步：包括最新的翻译和非文档内容的代码同步，可以随时发起 PR
  • 网络环境和本地化：如果发现任何这方面的问题可以直接发起 issue 讨论
  • 翻译讨论：可以随时发起 issue 讨论

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

  • 对于原文内容的讨论，而非中文译法本身。

    (作为译者，如果您存在语言上的障碍，我们可以提供必要的协助，但每位译者的时间其实都非常宝贵，我们还是鼓励大家先尽量试着自己在英文站发起并参与讨论)

  • 对于网站代码的优化，除非是特别针对中文站或国内环境的

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

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

4. 注意事项

  • 尽量保持原文的编码风格，不产生不必要的格式变化和改动。如果对格式有异议，建议直接在英文站讨论。
  • 我们有一个实验性的中文格式工具：zhlint 来检测中文格式，详见 6.1 如何使用 zhlint
  • 同步最新的翻译时，建议先查阅接下来的“如何定期同步最新的翻译等网站改动”章节。

5. 常见问题

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

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

  2. 如何发起 Pull Requests？

    • Clone 仓库
      image
    • 更改完毕后，推送到自己的仓库
    • 比较仓库，右侧为你的仓库和分支，左侧是需要并入的目标仓库和分支
      image
    • 选择比较的分支后，点击按钮：“Create pull request” 即可发起

  3. 如何定期同步最新的翻译等网站改动

    中文仓库配置了 AutoSync 自动任务，将定期 (目前为每天一次) 将英文版仓库的最新改动同步至本仓库的 upstream 分支。该任务也可以在需要时手动触发。

    如果要发起一次同步：

    1. 先从最新的 main 创建一个分支 (假设分支名为 sync)：[main]> git checkout -b sync
    2. 然后合并入最新的 upstream 分支：[sync]> git merge upstream
      • 记得解决所有冲突
      • 我们鼓励顺手翻译新产生的英文内容
      • 也可以暂时保留英文版不翻译，但记得就近加上 TODO: translation 注释，方便后续追踪
    3. 发起 PR 请求将这个分支合并回 main

    在发起 PR 的时候请注意：

    • 请提供当时 upstream 最新的 commit hash 以及之前一次同步时的 commit hash。
    • 之前同步时的 commit hash 可以通过这个页面快速查阅。
    • 请在正文附上两次同步之间的原文 GitHub Compare 页面。
    • 示例：https://github.com/vuejs-translations/docs-zh-cn/pull/450
    • 我们也提供了一个快速生成 PR 标题与内容的工具脚本，在保证本地仓库 origin/main 及 origin/upstream 分支无落后提交的前提下执行 pnpm sync pr，控制台将输出相应内容。更多用法可查阅 pnpm sync --help。

    在校对 PR 的时候请注意：

    • 建议参考 GitHub Compare 页面对比两次同步之间的变化。
    • 最终请务必使用“Create a merge commit”的形式合并以保留英文版的历史记录，方便后续持续同步和比对。

  4. 如何查看“我的贡献”？

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

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

  6. 如何使用 zhlint

  • 安装 zhlint

    npm install zhlint -g
# 或
yarn global add zhlint
# 或
pnpm add zhlint --global

  • 使用 zhlint 查看

    zhlint readme.md # 查看 `zhlint` 检测的结果

  • 使用 zhlint 修复

    zhlint readme.md --fix # 使用 `zhlint` 修复
Clone this wiki locally