翻訳済ドキュメントの更新についての方針を決める

[yokinist]

問題意識

翻訳済のドキュメントの更新できておらず、ソースとしての信頼性が低くなってしまっている

• 本家のドキュメントがどんどん更新されていくが追従できていないため
• 翻訳タイミングによってバージョンが異なっているため一貫性にかけているため
• 翻訳されたドキュメントがどのバージョンなのかが不明なため

備考

本家ドキュメントへの追従方針(仮)

- 本家で新規作成されたファイルは追加する
- 未翻訳のファイルが本家で更新されていたら更新する
- 翻訳の有無関わらず本家で削除されたファイルは削除する
- // #TODO: 翻訳済ファイルの追従方針を決める

考えられそうな方策(随時更新)

• 英文 / 日本文の混在を許容し、大きなアップデートのタイミングで差分をチェックし変更分は英文で上書きする
  • ※ 翻訳対象となっていたバージョンの英語ドキュメントがないと差分が分かりづらい
  • ※ チェック量が多くてしんどそう・・

あまり知見ないので、もし何かいいアイデアあればコメントにて意見いただけると嬉しいです！

関連: #186 (comment)

[5t111111]

これ、ほんと頭を悩ませるところですよね。僕も知見は知りたいといつも思っています…
翻訳プロジェクトのメンテが止まるのは、翻訳そのものよりも大体この問題だとも感じているので、方針を明確にして工夫して対応負荷を下げたいところです。

まず、僕の考えとしては、基本的な方針は、

英文 / 日本文の混在を許容し、大きなアップデートのタイミングで差分をチェックし変更分は英文で上書きする

でよいかと思っています。
翻訳済みの箇所と未翻訳箇所が混在していることよりも、翻訳ソースと翻訳成果のコミットにファイルごとにバラバラの差分があったり、ページ毎に翻訳ソースのバージョンが異なったり古い情報が残り続けることの方が、運営側の管理しやすさとしても、それを読む側にとっても良くないことだと考えるからです。

ただ、おっしゃるように、その方針でやるとしても、

※ 翻訳対象となっていたバージョンの英語ドキュメントがないと差分が分かりづらい
※ チェック量が多くてしんどそう・・

という課題があります。

これに対しては、

• 翻訳元としている repo (https://github.com/vercel/next.js) のコミットハッシュを明確にする (翻訳元バージョンを明確にする)
• 翻訳元側で更新があったときに、その差分を取得しやすくして、日本語側でも更新が必要なファイルを特定しやすくする
• 更新差分だけ翻訳できる仕組みを用意する

必要があると思っています。

これらの課題に対して、だいぶ前にやった別の翻訳プロジェクトでは、以下のような方法で工夫していました。
ある OSS ドキュメント翻訳事例 「Crystal のドキュメントを翻訳した」

ここでやったことは、要は、

• 翻訳作業用の「親」repoを作り、そこに git submodule として、翻訳元のrepo、日本語版のrepo、翻訳メモリ用のrepoを設定する
• 翻訳元の更新チェック・差分取得用の CLI ツールを用意して、そのツールで更新した場合、翻訳ソースのバージョンをコミットハッシュをとして記録する
• 翻訳メモリツールを使って、既存の翻訳は自動的に翻訳されるようにして、差分のみ未翻訳状態の日本語ファイルを生成できるようにする
• 翻訳はすべて翻訳メモリツールに反映するようにする
• 翻訳メモリツールから書き出したファイルを、日本語版の repo に最終的にコミットする

ということでした。
ただ、コントリビューターにこの作業をやってもらうのは大変なので、PRしてもらったものは実際には一度先行して日本語版に取り込んだ上で、メンテナが翻訳メモリへの反映などの手順を行なっていました。

ちょっと僕も現状の Nextjs-ja-translation-docs でどうするのがよいか結論が出ているわけではないので、あくまでこれは参考情報としてこういうやりかたがあるよ、という紹介になります。

ただ、翻訳元と日本語版で repo がわかれており管理者も異なるため、有償の翻訳支援プラットフォーム (Crowdin など) を用いても結局かなりの工夫が必要になるかと思うので、できるだけ管理を自動化しようとしたら、僕が上記したようなパターンに近くなるのではないかな、と思います。

そして、段階的にやるのであれば、まずは、

• 翻訳元としている repo (https://github.com/vercel/next.js) のコミットハッシュを明確にする (翻訳元バージョンを明確にする)

というところをやるのが良いのかなと思います。
(翻訳メモリとかは後からでもよいので、まずはファイルごとにどのバージョンが元になっているか混乱しているのを正す)

[yokinist]

圧倒的知見・・ありがとうございます🙏

基本スタンスとしては、いきなり完璧を目指すのは大変そうなので、できるところから段階的に進めていくのが確かにいい気がしています！

基本方針としては、いずれにせよ「英文 / 日本文の混在を許容し、大きなアップデートのタイミングで差分をチェックし変更分は英文で上書きする」をとり、そこに必要な作業を仕組み化していき、コストを小さくしていくといった感じになりそうですね。

• 翻訳元としている repo (vercel/next.js) のコミットハッシュを明確にする (翻訳元バージョンを明確にする)

これは間違いないですね・・・
前提として必要になってきそうなのでドキュメントにコミットハッシュを記載するようにしてみましょうか。

• 翻訳元側で更新があったときに、その差分を取得しやすくして、日本語側でも更新が必要なファイルを特定しやすくする

これが一番の壁ですね・・コミットハッシュが分かっても差分が分からないと何を変更すればいいのか分かりにくく実際にワークしなさそうなので、ここについての運用が固まったらイシューをクローズしたいと思います！

（コミットハッシュからたどって英文と日本文を比較して差分を確認するという手が一番原始的な方法としてありますが運用つらくて続かなさそうなので、他に楽できる方策を予め検討しておきたい気持ちがあります。いただいた記事を含め、自分も他の事例調べてみます!）