はじめに
Rustのドキュメントのうちいくつかは日本語に翻訳されていますが、それらは必ずしも最新の英語版と同期がとれているわけではありません。
最大の理由はもちろん翻訳のコストが高いからですが、英語版の更新をチェックしたり、更新があったときに日本語版にマージする作業も意外と大変ですし、モチベーション的にも辛いものがあります。
というわけで自動化できるところは自動化するようにツールを作ってみました。
いくつかmdbookの独自拡張に対応している部分があるのでmdbook向けとしていますが、Markdownの文書全般に使えると思います。
できること
まず前提として、翻訳されたMarkdownに原文がコメントアウトされて残っていることを仮定します。
その上で、以下の機能を提供します。
- 原文と「翻訳文中でコメントアウトされた原文」の一致確認
- 翻訳しなかった部分（ソースコードなど）の一致確認
- 原文が更新されていた場合の自動マージ
翻訳文の書き方
このツールは翻訳文の書き方に「原文の行はそのまま維持する」という制約を課します。
例えば
Apple
Orange
Peach
は以下のように翻訳します。
<!--
Apple
Orange
Peach
-->
りんご
オレンジ
桃
以下のようにしてもMarkdownのレンダリング結果としては同じになりますが、
正しく差分をチェックすることができなくなります。
<!-- Apple
Orange
Peach -->
りんご
オレンジ
桃
使用例
Rustのドキュメントで使うことを想定しているのでcargoからインストールします。
$ cargo install mdbook-transcheck
チェックする時は以下のコマンドです。
$ mdbook-transcheck src tgt
srcが原文のMarkdownがあるディレクトリ、tgtが翻訳文のあるディレクトリです。
差分がなければ表示はなく、戻り値0で成功します。
例えば上の例で翻訳した後に、Lemonが追加されたとします。
Apple
Orange
Lemon
Peach
この状態でチェックをかけると
$ mdbook-transcheck src tgt
Error: lines has been inserted to the source file
source --> src/fruits.md:3
|
3 | Lemon
|
= hint: The lines should be inserted at tgt/fruits.md:3
となって、原文側にLemonが追加されたのでtgt/fruits.mdの3行目に挿入するようヒントが表示されます。
さらに--fixオプションを付けると
$ mdbook-transcheck --fix src tgt
Insert: tgt/fruits.md:3
となって翻訳文側にLemonが挿入されます。
この状態でgit diffすると
$ git diff
--- a/tgt/fruits.md
+++ b/tgt/fruits.md
@@ -1,13 +1,13 @@
<!--
Apple
Orange
+Lemon
Peach
-->
りんご
オレンジ
桃
とLemonが挿入されたことが分かるので、レモンを追加すればいいわけです。
CIでの実行
CIでは以下のようなことができる想定です。
（実際の運用はこれからRust-by-Exampleの翻訳プロジェクトで試す予定です）
- 各PR毎にチェック
これによって編集時のミスなどによりコメントアウトされた原文やソースコードが壊れていないことを確認できます。
- 定期的に原文の最新リビジョンとチェック
これによって原文側の更新によって翻訳文と差分が発生したかどうかが確認できます。
また、--fixオプションで更新分を自動で取り込んでPRを生成することもできると思います。