Elixir School は Elixir 言語を学ぶためのサイトで、Elixir にしては珍しく日本語として翻訳され提供されています。
この記事では Elixir School の日本語訳へ貢献する方法を書きます。
環境準備 git clone
Elixir School のページは以下のリポジトリにて管理されています。
ですので、こちらのリポジトリを自分のアカウントに fork しておき、それを git clone しましょう。
今回は日本語訳なので、ja/lessons ディレクトリ下にオンラインのページに対応する Markdown ファイルが格納されています。
ファイルのパスはオンライン上の URL パスと一致しています。
例えば https://elixirschool.com/ja/lessons/basics/basics/ の場合だと
対応するページはリポジトリ上の js/lessons/basics/basics.md を元に生成されます。
翻訳対象となるページを見つける
まずは翻訳対象となるページを見つけましょう。実は今までに日本語訳をしてくれた方々のおかげで、ほとんどのページは翻訳が完了しています。
ただ翻訳が完了しているページでも、最新版に追従できていないことがあります。
例えば新しいバージョンの Elixir がリリースされたりして、オリジナルのドキュメントに更新が入った場合などです。
これら最新版になっていないページを見つけてくる必要があるのですが、幸いなことにオンラインのドキュメント上ですぐに見分けることができるようになっています。
和訳が最新のページ
和訳が古いページ
2018/12/18 現在の基本ページの様子 https://elixirschool.com/ja/lessons/basics/basics/
上記のように最新のものは「この和訳は最新です」と表示されていますが、そうではないものは和訳が古いと表示されます。
なので和訳が古いページを翻訳の対象として選びます。
また該当するファイルに関連する Pull Request がないかを確認しておきましょう。これは同じ作業を別の方がしてしまうことを避けるためです。
https://github.com/elixirschool/elixirschool/pulls にあがっているチケットを見て、日本語訳系のものがないかチェックします。[JP] とプレフィックスがついていることが多いようです。
翻訳
以下に対応方法を記載しますが、Contribution Guidelines があるのでさらっと確認をしておきましょう。
対象のページを見つけたところで翻訳の作業に入りますが、前項で説明した通り基本的には翻訳されているもののバージョンを最新に上げることが必要になります。
そのため現在の翻訳バージョンと、オリジナルの現在のバージョンの差分を取り、その差分について翻訳作業をしていくことになります。
現在の翻訳のバージョンは Markdown ファイルの先頭に書かれているバージョン番号から確認できます。以下 lessons/basics/basics.md を対象に説明。
この例では日本語訳のバージョンは 1.1.2。対するオリジナルのバージョン(en/ にあります)は以下の通り 1.2.1 です。
そのためオリジナルのバージョン 1.1.2 から 1.2.1 の間に入った変更を確認し、その変更について翻訳をします。
1.1.2 の変更を git blame などで探し出すと、このコミットが 1.1.2 のものとなるようです。
なので、この後に入った変更を en/lessons/basics/basics.md に対して確認します。
まとめて確認する場合は以下のように git diff で差分確認します。
$ git diff 1abd22e116ba3d6b16565637889011257e86658c f36644dfd91c49139a276f0e977ed13599297db2 en/lessons/basics/basics.md
1個1個の差分確認は git log -p で。
$ git log -p 1abd22e116ba3d6b16565637889011257e86658c.. en/lessons/basics/basics.md
差分について翻訳
差分について確認できたので、その差分について翻訳していきます。ここは粛々と対応しましょう。
翻訳が終わったら日本語訳ファイルの先頭にあるバージョンをオリジナルのものに合わせましょう。上の例では 1.1.2 から 1.2.1 に変更します。
翻訳の確認
Elixir School は README.md にあるように Jekyll を使っています。そのため Gemfile で指定されているバージョン以上の ruby をインストールします。また bundler もインストールしましょう。ruby と bundler のインストール方法については割愛します。
インストールができたら elixirschool のルートディレクトリにて以下を実施して、http://localhost:4000 へアクセスします。
$ bundle install
$ bundle exec jekyll s
該当のページを表示して、訳が間違っていないか、「この和訳は最新です」と表示されているか、レイアウト崩れなどがないか確認しましょう。
Pull Request を送る
あとは変更内容をコミットして Pull Request を送りましょう。Pull Request を送る際は以下の対応をしておくと良さそうです。
- 件名のプレフィックスに [JP] をつけて日本語訳であることをわかりやすくする
- コメントに @elixirschool/japanese を含める(Elixir School には日本語訳チームがあるようなので)
まとめ
ということで Elixir School へ日本語訳を Pull Request する際の方法をまとめました。
少し前に Pull Request を行った際の対応をまとめただけの記事となりますが、これで次回対応時にはスムーズに進められそうです。
Resources
- Elixir School 日本語訳 · Elixir School https://elixirschool.com/ja/
- elixirschool/elixirschool: Premier destination to learn and master the Elixir programming language https://github.com/elixirschool/elixirschool
- 以前行った Pull Request https://github.com/elixirschool/elixirschool/pull/1615
- 初心者向けサイトElixir Schoolを日本語訳した - Qiita https://qiita.com/zero310/items/1adcaa19926d69771b85