关于如何进行英文版同步的问题
wxsms opened this issue · 21 comments
目前因为中文仓库的同步工作有些滞后，对翻译与校对工作造成了一定影响（见 #119 ），因此希望可以尽快确定同步方式（手动 or 自动），以及确定流程细节。
我个人之前有尝试过日文仓库提供的 https://github.com/vuejs-translations/ryu-cho action，具体请见 我的 fork，并对它的工作方式进行了一定的考察，总结如下：
- 从 https://github.com/vuejs/docs/commits/main.atom 这个 feed 找到最近的提交（显而易见的是这里是有数量限制的，所以第一次同步大概率要手动进行，并且后续 action 的执行频率不能太低，不然也会漏提交）
- 过滤掉所有时间比 latest run 更早的提交（而非从 git history diff 出新的提交，这里可能也是一个会导致漏提交的点，考虑到上游仓库可能积攒了一批 commit 以后一次性 push）
- 为每个提交创建一个 branch，并尝试 cherry pick，成功则发起 issue+PR，失败则只发起 issue
总体来说，我觉得这个工作流可用，但也存在一些可能出问题的环节，以及可能会带来比较大的 noise（上游每个提交在这里均生成 1 issue + 1 PR，参见日文仓库 https://github.com/vuejs-translations/docs-ja ）。
大家如果有更好的提议，欢迎提出。谢谢。
搬运来自 @KimYangOfCat 的评论：
这个问题发生的本质原因是本仓库的英文同步不及时
最好将英文分支最新状态全部同步过来，目前本仓库的同步似乎依旧是人手工同步的，是否考虑引入一些自动化同步手段？
目前译者和校对者似乎也在承担着仓库具体文件的一些同步工作，我个人认为这会带来更多的冲突与工作量。
理想状态应该是这样的，自动化同步手段完全负责全部英文内容的同步，并集中解决所有翻译冲突，个人译者和校对者只关注译文的翻译和校对，这样能提升仓库内容的实时性以及编译的稳定性
总的来说，目前仓库的英文同步流程方式还不是很明确，既有仓库维护者的统一同步，也有翻译者和校对者针对单个文件的同步，这样的合作方式，有可能造成的结果如下：
- 可能有多方修改内容的冲突：维护者与校对者所有修改内容的冲突，维护者与英文原文的冲突，校对者与英文原文的冲突
- 文档内容更新不及时，不同步：有最新校对过的文档可保证内容最新，而其他长时间尚未校对文档内容可能十分落后，由此每篇文档内容更新不能保持同步
如果不修改类似的流程，此类问题依旧会时常发生，我个人提议是使用自动化同步手段，统一英文内容的同步，将同步工作从校对者任务中解耦，保证每位参与的同学任务清晰单一。
实现自动化同步也很简单，添加一个action脚本，自动每天从英文仓库拉取最新状态向本仓库提交PR即可，action Marketplace 有成熟现成的脚本可用
搬运来自 @initdc 的评论：
流程建议:
-
使用 3 个
branch来构建翻译同步体系upstream: 由 bot 自动同步的英文仓库主分支current: 基于此分支进行 翻译工作，后续人工git cherry-pick一部分合并, 控制同步粒度，以控制更新翻译的工作量main: 翻译分支
-
贡献者修改代码须新建分支，分支名可参考
docs/:user或docs/web-components, 这样可以方便贡献者后续方便的同步fork仓库，不必担心上游仓库的更新，主分支也只需git cherry-pick，即可避免一些因合并顺序导致的提交冲突，也无需rebase， 就保证了 合并信息的 规范化 -
加入基于
commitlint的合并信息规范 及 基于 合并信息的 语义化版本， 同时也得到了直观的 CHANGELOG。即使不是软件，多打两个tag，标记下进度，总不算小题大作。
及时同步迫在眉睫，我支持实验性引入，看下效果。
@initdc 的建议非常中肯，支持
加入基于commitlint 的合并信息规范 及 基于 合并信息的 语义化版本， 同时也得到了直观的 CHANGELOG。即使不是软件，多打两个tag，标记下进度，总不算小题大作。
关于最后一条建议，这应该算是发布与规范相关的流程了，我认为不仅适用于中文文档，同样适用于英文文档，但英文文档目前的 commit 信息也没有规范化，不知是否可以考虑对英文文档也提出相关 issue 讨论一下？看看英文仓库维护者的想法？毕竟英文仓库如果有更明确的 release，也方便其他语言仓库的维护者明白相关英文内容是否到了值得翻译的地步。
如果两个仓库能保持同样的发布和规范流程就更好了，不行的话，本仓库自行构建相关流程也可以。
关于“使用 3 个 branch 来构建翻译同步体系”的建议，我们是否可以简化为两个分支？即，一个upstream，一个main。人工 cherrypick 会带来一定的工作量。
另外，我注意到 @initdc 同学已经发起了相关的 PR，其中关于自动同步的 action 看起来要比我一楼提到的要简单一些。如果我没理解错的话是：英文仓库代码自动同步到 upstream 分支，由维护者手动合并到该仓库的主分支，并解决冲突。我个人倾向于这个解决方案。
另外关于 commitlint 的想法，我持保留态度。文档项目对于 changelog/tags 的依赖个人认为没有一般项目大，更多还是专注于内容的及时性以及准确性。
基本是一个方法论的问题
git cherry-pick 是控制 commit 合并粒度，与翻译工作来说，用处不大，毕竟翻译只需要最新的版本，这也表明了两者代码结构上的弱依赖，原文档更像是需求，而不是等待更新或修复的程序。但是这种方法可以跟踪依赖，比如本次.md内的vue组件。
从upstream到main分支，看起来是更新不同步的问题，其本质是翻译基本是二次创作，二者必然是内容冲突的。只有没翻译的文件才没有合并上游的冲突。从upstream到main的合并，更新的上游文件需要更新翻译，控制进度，追踪依赖等诸多问题。昨天我也思考了关于current分支存在的必要性，自己确实有些彷徨。不过我还是认为它有存在的必要性，current作为一个中间层，让一些问题，流程都更加可视化。可以先引入试试，两种路都走走，看看实际效果。最后再不济upstream可以无痛merge到current分支。
翻译工作更适合文件(file/folder)粒度的更新。比如我要更新翻译guide内的文档: 拉取upstream到新文件夹, 删除current里的guide文件夹，新的放过来。翻译工作拉取current到自己的新分支(例如docs/initdc)。翻译工作量是可见的，由文件层面予以约束。谁翻译哪个文件是可定的，可替代现行的认领机制。也避免贡献者不明晰翻译范围，进行了工作，却合并不进分支，造成心理挫败。
写代码的前辈做出过很多努力，我们也许不需要发明，发现就已经足够震撼。.patch 文件看起来也适合翻译文件，这是对更改范围的可视化，可以探讨一下。可见的问题有 .md 到 网页的展示是否受到影响。
最后的提交规范化的问题: 这只是一个选择问题，这就像肯尼迪的登月计划: We choose go to the Moon. We choose go to the Moon!
规不规范化都能成为有影响力的项目，只是走过的路不同而已。
commitlint 也许不是最好的，但是 是当下最好的，我还是推荐使用它。
英文仓库代码自动同步到 upstream 分支，由维护者手动合并到该仓库的主分支，并解决冲突。我个人倾向于这个解决方案。
我也看到了 @initdc 提交的PR #122 ，但是这个解决方案其实相对于手动更新并没有减轻多少工作量，可能只是少了一个 git fetch 的过程，因为更新的主要工作量其实就在合并分支上, 维护的同学也可能因长时间忘记合并 upstream 而导致内容更新不及时。所以想要及时更新内容，可能需要具有提醒行为的方案，比如提交 PR:
我优化了一下，方案如下：
英文仓库代码自动同步到 upstream 分支，并自动合并入 main 分支，如果有冲突需要解决的情况，提交 PR，并标注冲突点，再由人工去解决冲突。这样会节省很多工作，同时需要人工干预时也有 PR 提醒。
上述方案，其实已经在印记中文团队维护的 webpack 文档仓库中得到了成熟的应用。
如果允许的话，我们可以寻求印记中文团队的帮助，他们已然有一套完整的工具可帮助减轻本仓库同步的工作量。作为印记中文团队的一员，我可代为前去沟通。
如果本仓库想自己造工具的话，上述方案也是值得作为造工具时的考量哒。
上述工作流确实很出色, 让我想到了顶流bot: @dependabot.
通过比较也发现了@docschina-bot 的一个不足:
dependabot 针对一个 deps， 旧PR未合并 新PR 已产生后，会自动关掉旧PR
这个问题也情有可原, 毕竟deps只是分析一个文件, 找出冲突, 再分析两次PR的文件差异（package.json ...lockfiles）
自动合并, 会产生相当部分的文件改动. 不过鉴于上游文档也是由人编写的, 文件改动也有其逻辑性.
基于 提交记录 对 提交记录的 翻译更新, 虽然这是终极追求, 就精力消耗而言我认为还是有点大.
docschina-bot 如果能改进这点, 相信能 make translating great (again?)
@initdc 这是一个翻译平台，它确实解决了很多问题，同步，翻译，格式化等等，它确实很棒，但它却不一定适合 Vue Docs。
它的流程要求和现在的仓库流程完全不同，它几乎是完全脱离了 github 的 PR 流程。这点有好有坏吧。好处肯定是它的功能完善，但缺点是是一旦脱离github，有意愿继续帮忙翻译的开发者会少很多，而且它似乎也不能像 github 一样追踪到每一位翻译者的贡献。这对于大公司的项目来说问题不大，因为他们会有人专门负责文档。但是对于Vue这样社区驱动的开源项目，如果没有贡献统计，就无法为社区翻译者提供正向反馈。
它自有规则，却也受限于它的规则。它一般是基于文件夹做多语言翻译，文档站点开发的过程中就得考虑很多问题，比如组件的国际化等等，而目前 Vue 还是基于仓库做多语言翻译。基于仓库的方法在文档站点开发上就相对灵活一些，所以这部分还是蛮有冲突的。
总的来说，这个平台目前的功能可能更适合公司成员内部合作使用，而根据 Vue Docs 现有的结构和流程，我认为还是不太适用的。
Git Localize 确实是个选项，我之前关注过一段时间，也简单试用过。如果我们打算把这个平台用起来，最好是所有语言的翻译一起行动，感觉 Vue 团队先有个结论比较好。我来保持跟进然后跟大家同步结论好了。
其余的部分我们试试看效果先。
另外我们目前处在集中翻译与校对的阶段，短期和英文版不同步是难免的，不只是流程可以解决的，也不是永远存在的问题。不论怎样，我个人觉得我们先专注在完成这一波翻译和校对，可能很多问题自然就解决了。
一个可操作性较强且不需要很高成本的方案是我们
- 约锁定一个英文版的提交 (比如当前最新的 commit https://github.com/vuejs/docs/tree/6ea4166d023fd3c33086d493035da40333b24627)，然后
- 针对这个版本进行翻译和校对，
- 等这一波完成了，再一次性做一次 sync up，然后
- 保持日常同步，颗粒度可以到 commit 级别，可以引入 cherry-pick，各自流程届时都可以跑起来。
大家觉得如何
是否要应用 Git Localize 确实需要 Vue 团队内部先给定结论。不过想要所有语言一起行动的话，还是会有一定的工作量的，比如当前文档结构需要稍作修改，vitepress 中自定义的组件也需要进行国际化。
赞同先锁定一个英文 commit，集中完成当前这波翻译和校对。如果锁定的话，希望能在 #8 中，具体说明，方便参考。
多补充一个建议，如果要选一个 commit 的话，我倾向于 https://github.com/vuejs/docs/tree/9b1e387273c75908cc6c1227c968d139c874147c
主要原因有两个：
- 这是小右集中维护和撰写的最后一次 commit，后面的提交基本都是从社区来的
- src 目录下迄今为止只有 testing 一个页码改动较大，其他页面都只是几行改动而已
GitHub commits: https://github.com/vuejs/docs/commits/main
GitHub compare: vuejs/docs@9b1e387...main
如果大家觉得 OK 的话，我们可以选这个 commit 作为集中翻译与校对的参考版本
我认为 OK @Jinjiang
多补充一个建议，如果要选一个 commit 的话，我倾向于 https://github.com/vuejs/docs/tree/9b1e387273c75908cc6c1227c968d139c874147c
主要原因有两个：
- 这是小右集中维护和撰写的最后一次 commit，后面的提交基本都是从社区来的
- src 目录下迄今为止只有 testing 一个页码改动较大，其他页面都只是几行改动而已
GitHub commits: https://github.com/vuejs/docs/commits/main GitHub compare: vuejs/docs@9b1e387...main
如果大家觉得 OK 的话，我们可以选这个 commit 作为集中翻译与校对的参考版本
针对目前未认领/未开始的校对/翻译，我赞同这个处理方式。不过貌似目前这一波的校对进度已经接近尾声了，已完成的校对很多是对照当时最新的提交来进行的，或者有一部分正在校对中的，有可能也是以最新提交为对照。这一批工作量我们也不太可能废弃，因此如果要补充一下的话，我觉得：
- 推荐以 https://github.com/vuejs/docs/tree/9b1e387273c75908cc6c1227c968d139c874147c 作为校对对照
- 若以最新提交对照完成了校对（已合并或未合并），我们也不做强制要求
这样如何？
若以最新提交对照完成了校对（已合并或未合并），我们也不做强制要求
恩，我觉得没问题
@Jinjiang @wxsms @veaba @KimYangOfCat
#136
各位成员好，我已经借助 vue-docs-tr-helper 插件手工比对将文档同步到 3月1日 的英文文档提交
这个提交离最新的提交已经相当近了。
# 数天前克隆了中文文档仓库
git clone https://github.com/vuejs-translations/docs-zh-cn.git
# 根据目前中文文档的 main 分支 检出了一个 shenqingchuan/sync 分支
git checkout -b shenqingchuan/sync
# 拉取英文文档当时的最新 5cd2bdc67661b4fe629eed68764904e4639925e7
git pull en main
# ... 进行 merge 的审查、校对
# 确认没有冲突、文档内容都能按行对应后
git commit -m "docs(cn): manual sync from English main."
# 第一次推送
git push
# PR 检查发现和当前中文文档 main 分支有冲突
git pull origin main
# ... 解决完冲突
git commit -m "docs(cn): merge with latest Chinese docs."
# 第二次推送
# 然后发起 PR@Jinjiang @wxsms @veaba @KimYangOfCat #136
各位成员好，我已经借助 vue-docs-tr-helper 插件手工比对将文档同步到 3月1日 的英文文档提交
我不太确定这个大 PR 是否有将最近合并的 Review PR 覆盖掉的情况。
理论上 3 月 1 日之后如果有合入，可能会被我的第一次同步英文文档覆盖。
目前我的这个 PR 和主分支没有冲突。
@Jinjiang @wxsms @veaba @KimYangOfCat #136
各位成员好，我已经借助 vue-docs-tr-helper 插件手工比对将文档同步到 3月1日 的英文文档提交我不太确定这个大 PR 是否有将最近合并的 Review PR 覆盖掉的情况。 理论上 3 月 1 日之后如果有合入，可能会被我的第一次同步英文文档覆盖。 目前我的这个 PR 和主分支没有冲突。
过了一遍 PR，目前发现 src/guide/scaling-up/ssr.md 这篇文章可能是如你所说，被覆盖了，可能需要确认一下。其它文章暂时没发现问题。其它一些小问题我在 PR 内 comment 了。谢谢！
从英文版同步的 PR 已合并。
鉴于已加入自动同步 upstream action，中文仓库与英文仓库的 main 分支也已十分接近了，该 issue 就先行关闭。后续如有其它问题可以再做针对性的讨论。谢谢。
我的执行流程是：
# 数天前克隆了中文文档仓库 git clone https://github.com/vuejs-translations/docs-zh-cn.git # 根据目前中文文档的 main 分支 检出了一个 shenqingchuan/sync 分支 git checkout -b shenqingchuan/sync # 拉取英文文档当时的最新 5cd2bdc67661b4fe629eed68764904e4639925e7 git pull en main # ... 进行 merge 的审查、校对 # 确认没有冲突、文档内容都能按行对应后 git commit -m "docs(cn): manual sync from English main." # 第一次推送 git push # PR 检查发现和当前中文文档 main 分支有冲突 git pull origin main # ... 解决完冲突 git commit -m "docs(cn): merge with latest Chinese docs." # 第二次推送 # 然后发起 PR
git checkout -b shenqingchuan/sync 之前应该先 git pull origin main 吧