mdBookの多言語対応について
はじめに
mdBookはRust製のドキュメントビルダーです。公式のドキュメントを含め、多くのRustプロジェクトに採用されていますが、多言語対応について特別なサポートはされていません。
そのため翻訳版を提供する場合、それぞれの翻訳者が独自のワークフローを構築している状況でした。
しかし、2023年に入り mdbook-i18n-helpers というmdBookプラグインがリリースされ、Comprehensive Rust （GoogleのAndroidチームで使われているRust入門用ドキュメント）の多言語対応に使われるようになりました。
この記事ではこれまでのmdBookの多言語対応の検討と、mdbook-i18n-helpersの概要についてまとめてみます。
mdBookの多言語対応検討
多言語対応のissueは古く、2015年に提案されています。
提案された当初は、各言語ごとに独立したMarkdownファイルを用意して、ファイル単位で翻訳していく方式が主に検討されていたようです。
また、2020年にはそれを実装したプルリクエストが出されています。
ただ、全体的にあまりポジティブな反応はなく、提案されただけで終わってしまっている状況でした。
ファイル単位での翻訳の問題点
ファイル単位で翻訳する際の問題点として、翻訳の継続的な追従が難しい点が挙げられます。
ある時点で英語から日本語に翻訳が完了したとして、その後英語版が更新された場合
- 英語版の差分をとり、どこが変わったかを確認する
- 変わった箇所が日本語版でどこに対応するかを調べて再翻訳する
という手順が必要となります。一般的にボランティアでの翻訳はリソースが足りていないので、これを人手でやるのはほとんど不可能です。
原文がめったに更新されなければいいのですが、Rustの公式ドキュメントはかなり頻繁に更新されるので、翻訳版はいつまでも古い内容のまま、という状態になってしまいます。
Rustの日本語版ドキュメントにおいてこの状況を（多少でも）改善するために、以前このようなツールを作ったりしました。
mdbook-i18n-helpersの登場
mdbook-i18n-helpersはComprehensive Rustの著者の一人であるMartin Geisler/@mgeislerさん（GoogleのAndroidチームに所属のようです）によって開発されました。
元々mdBook本体への機能追加として考えられていたようですが、現行のプラグインシステムで実現可能であるためプラグインとしてリリースされることになりました。
mdbook-i18n-helpersの特徴は翻訳にGNU gettextを使っている点です。GNU gettextでは原文の文字列と翻訳後の文字列のデータベースを用意し、それに基づいて翻訳版を生成します。
例えば以下はComprehensive Rustの日本語用データベースの一部です。
#: src/index.md:7
#, fuzzy
msgid ""
"This is a free Rust course developed by the Android team at Google. The "
"course covers the full spectrum of Rust, from basic syntax to advanced "
"topics like generics and error handling."
msgstr ""
"この資料は、GoogleのAndroidチームによって開発された3日間のRust講座です。本講"
"座では、基本構文からジェネリクスやエラー処理など、幅広い内容をカバーします。"
"また、最終日にはAndroid専用の内容も含まれています。"
msgidに原文文字列を、msgstrに翻訳後文字列を並べたデータベースとなっています。
元々のMarkdownファイルからをこのデータベース形式を抽出する作業は自動的に行われ、原文が変更された際にはデータベースを再抽出し、元のデータベースからのマイグレーションも自動で行われます。その際、多少の変更があった文字列についてはあいまい検索によって対応が取られ、fuzzyフラグを付与することで翻訳の見直しが必要であることが示されます。
従来のファイルごとの翻訳ではコードブロックの翻訳も課題でした。コードブロックの大半は翻訳とは無関係にもかかわらず、原文の修正は手動で取り込むしかありません。
mdbook-i18n-helpersはコードブロックのうちコメントや文字列リテラルだけをデータベースに抽出します。これによりソースコード自体の修正が翻訳と無関係になり、原文の修正がリアルタイムに翻訳版にも反映されることになります。
また、GNU gettextはソフトウェアの多言語対応に古くから使われてきたツールであり、そのデータベースフォーマットに対応したツールも数多く存在します。GNU gettextを利用することでその周辺エコシステムの恩恵にあずかることができます。
mdbook-i18n-helpersの課題
基本的な翻訳の枠組みが機能することはComprehensive Rustで示されていますが、実際にはまだ手軽に多言語対応できるという状況ではありません。
例えば、言語切り替えボタンを追加するにはmdBookのテーマ機能を使って自身でベースとなるHTMLを書き換えなければなりません。また、検索エンジンがクロールできるように各言語へのリンクも手動で追加する必要があります。これらはすでにissueとして挙がっており、mdBook本体への機能追加を含めて順次対応されているようです。
Rust公式ドキュメントの対応
Rustの公式言語ドキュメントである "The Rust Programming Language" では以下のissueで多言語対応の管理について議論されており、Martin Geislerさんがmdbook-i18n-helpersについて提案されていますが、今のところ特に反応はないようです。
一方、"Rust By Example" ではmdbook-i18n-helpersを使うようプルリクエストを出してみたところ、マージしていただくことができました。"Rust By Example" は今でもオリジナルの著者の方が一人でメンテナンスされているため、こういった大き目の変更でもご本人が納得さえすれば受け入れられやすいです。（実際それを狙ってプルリクエストを出した部分もあります）
というわけで "Rust By Example" については今後日本語版のマージを試みる予定です。興味のある方は以下のissueをご覧ください。
おわりに
mdBookの多言語対応については、現時点でも特に決まった方式が現れたわけではありません。ただmdbook-i18n-helpersの登場により、翻訳の環境としてはかなり改善されたと感じています。課題となっている部分がクリアされていけば、mdBookにおける多言語対応のデファクトスタンダードになれるポテンシャルはあると思いますし、今後の改善に期待しています。
Discussion