Rust by Example 日本語版が公式に公開されるまで
はじめに
2024/07/25 にリリースされた Rust 1.80.0 にて Rust by Example の日本語版が公式に公開されました。画面右上にある地球儀のアイコンから日本語を選択可能になっています。
この取り組みを始めたのは2023年の10月頃だったのですが、さまざまなレビュー待ちやRustにおけるドキュメント公開フローをよく分かっていなかったことによる失敗もあり、最終的には1年近くかかってしまいました。
Rustはコンパイラの開発などかなり良くドキュメント化されている（Rust Compiler Development Guide）のですが、ドキュメントの管理についてはほとんど資料がなく、Zulip で聞かないと分からないようなこともありました。
この記事ではこの1年でやってきたことを時系列で書いていきます。Rustのドキュメントに貢献したい人には参考になる部分があるかもしれません。
2023/10: Rust by Exampleのリポジトリに翻訳ワークフロー追加の提案
まず初めに、Rust by Exampleのリポジトリに翻訳のためのワークフロー追加を提案しました。Rustの公式ドキュメント（doc.rust-lang.org以下でホストされているもの）は、ドキュメント毎に独立したリポジトリで管理されています。例えば
- The Rust Programming Language: https://github.com/rust-lang/book
- Rust by Example: https://github.com/rust-lang/rust-by-example
- The Rustonomicon: https://github.com/rust-lang/nomicon
といった具合です。
各リポジトリの管理はRustコンパイラの開発とは独立しており、Rust by Example の場合はオリジナルの著者がメンテナンスを継続されているようです。
このPRが2023/12にマージされたことで、Rust by Exampleの日本語版公開に向けて作業を進めることになりました。
2024/01: 日本語リソースの追加
2023/10のPRは却下される可能性も十分あると思っていたため、実際の翻訳の移植作業はしていませんでした。Rust by Exampleの日本語版としてはすでに https://doc.rust-jp.rs/rust-by-example-ja/ があったので、ここから翻訳を移植するために
にて意見を求めつつ、日本語リソースの移植作業を行いました。
最終的に以下のPRを作成し、2024/02にマージされました。
2024/02: rust-lang/rustのサブモジュールアップデート
実はこの時点では https://github.com/rust-lang/rust-by-example への変更が doc.rust-lang.org のドキュメントにどのように反映されるのかは全く知りませんでした。
実際に公開されている内容と、元リポジトリのコミットログを比較してみると、どうもrust-lang/rustにサブモジュールとして取り込まれているリビジョンが反映されているようだ、というのが分かってきました。
具体的には以下のディレクトリに公式から公開されているドキュメントのサブモジュールがまとまっています。また、このディレクトリのコミットログを見ると、2週間毎にサブモジュールのアップデートが自動で行われているようでした。
この時点で次のアップデートは2024/02/27予定だったため、そこまで待って無事日本語リソース入りのリビジョンに更新されました。
2024/03: Rust 1.77.0 リリース
リビジョンは更新されたのですが、それですぐに公式ドキュメントが更新されるわけではなく、Rustのリリースタイミングに合わせて更新されるようでした。最も近いRust リリースは 2024/03/21 の Rust 1.77.0 なのでそこまで待ったのですが、公開されたものに日本語版は含まれていませんでした。
どうも、ドキュメントの公開もRustのリリーストレインモデルに合わせてnightly/beta/stableの3段階となっており、サブモジュールアップデートがnightly相当なので、stableとして公開されるのはそこから2バージョン後、ということのようでした。
2024/05: Rust 1.78.0 リリース
Rust 1.78.0 まで来たところでようやく日本語リソース入りのリビジョンが公式に反映されました。具体的には冒頭に示した地球儀アイコンに日本語の項目が出現しました。これで完了かと思いきや、日本語を選択した先は404 Not Foundになっています。
なぜ日本語版のページが生成されていないのか全く分からなかったので、Zulipで聞いてみたところ、doc.rust-lang.org以下のページはRustコンパイラのビルドプロセスの途中で生成されていると教えてもらえました。
Rust by Exampleの場合、コミット毎にGitHub Actionsによりページを生成していたため、その成果物が何らかの方法で送信されているようなイメージだったのですが、どうもこの成果物は公式のリソースとは一切関係ないことが分かりました。
翻訳ワークフローの追加作業では各言語の翻訳版も生成するためにGitHub Actionsのスクリプトを変更したりしていたのですが、これは全く公式に反映されていなかったということです。
2024/05: Rustに翻訳版ビルドプロセス追加の提案
というわけで翻訳版をビルドするためにはRust本体に手を入れる必要があることが分かりました。
具体的には以下の2点が必要でした。
- src/bootstrap/src/core/build_steps/doc.rs
このファイルはRustのビルドプロセスにおいてドキュメント生成の方法を定義しています。今回はどのドキュメントでどの翻訳版を生成するかを定義するためのエントリを追加しました。
- src/tools/rustbook
Rust のドキュメントは mdbook で生成されますが、Rustのビルドプロセスでは mdbook をそのまま使うのではなく、mdbookをラップしてカスタマイズした独自の rustbook 経由で生成しています。これを変更して翻訳版を生成する方法を追加しました。
最終的なPRは以下で、2024/06/06にマージされました。
2024/06: nightlyドキュメントに反映
これは全く別件で気づいたのですが、doc.rust-lang.org以下のドキュメントは普段見ているstableバージョン以外にnightly/betaのドキュメントも存在します。
例えば Rust by Example であれば
- nightly: https://doc.rust-lang.org/nightly/rust-by-example/
- beta: https://doc.rust-lang.org/beta/rust-by-example/
- stable: https://doc.rust-lang.org/rust-by-example/
です。nightlyはRustのnightlyビルドと同時に更新されるので、RustのPRがマージされた翌日にはここで確認することができます。
これでようやく日本語版をdoc.rust-lang.org以下から見ることができるようになったのですが、
一部の翻訳が行われず、英語のままになっているという問題を発見しました。
これは翻訳管理に使っている mdbook-i18n-helpers のバグで、急いで 修正PR を出したのですが、 Rust 1.79.0 リリース（2024/06/13）には間に合わず、バグが残ったまま beta に取り込まれることになりました。
2024/07: Rust 1.80.0 リリース
nightlyに反映されてから2バージョンたったので、stableとして公開されました。先の述べたように、一部翻訳が行われないバグが残ったままになっていますが、これはRust 1.81.0 リリース時に解消する見込みです。
また、ビルドプロセスにいろいろ手を入れた関係で 1.80.0 のコントリビュータリスト に94位で入っていました。
まとめ
というわけで、ここ1年ほどの作業をまとめてみました。1年かかったといってもほとんどは待ち時間で、例えばnightlyドキュメントを見る方法などをあらかじめ知っていれば、もっとスムーズに進んだ気がします。とはいえ今回で全体のフローをかなり理解できたので、今後は他のドキュメントにも適用できるといいかな、と思っています。
Discussion