(4日目) Sphinx の文書を翻訳してみよう (sphinx-gettext-helper)

こんにちは。今日は昨日の続きでもっとかんたんに Sphinx の翻訳する方法を紹介します。。

昨日紹介したとおり Sphinxgettext 機能がサポートしているのは
pot ファイルの生成までで、それ以降の変換処理は手動で行う必要があります。

この変換処理は文章が大きくなって、構成する rst ファイルが増えれば増えるほど手間がかかるので、
何らかの方法で自動化する必要があります。
たとえば @ianlewis さんは Sphinx 1.1 i18n 機能紹介 の中で二つのシェルスクリプトを紹介してくれています。


多くの人がこのようなスクリプトを書いているようなので
車輪の再発明ではあるものの sphinx-gettext-helper というスクリプトを作成しました。
sphinx-gettext-helper を使うと面倒な gettext コマンド群の操作が不要になります。

インストール

sphinx-gettext-helper のインストールは他の python スクリプトと同様に easy_install で行います。

$ sudo easy_install sphinx-gettext-helper

sphinx-gettext-helper は msginit, msgmerge, msgfmt コマンドを利用します。
もしこれらがインストールされていなければ、合わせてインストールしておきます。

Sphinx プロジェクトの設定

gettext を使う場合と同様 conf.py に

locale_dirs = ["locale"]
language = "ja"

という設定を書き足します。
sphinx-gettext-helper は locale_dirs の最初のディレクトリにメッセージカタログを作成します。

rst ファイルから po ファイル、mo ファイルを生成する

sphinx-gettext-helper では一回のコマンド実行で pot ファイルから po ファイル、mo ファイルを生成することができます。*1

$ make gettext
$ sphinx-gettext-helper -p _build/locale --update --build
.. 完了.

sphinx-gettext-helper は Sphinx によって生成された pot ファイルを検索し、すべての pot ファイルを po ファイルに変換します(--update オプション)。
なお、内部では msginit, msgmerge コマンドを利用しているので、初回の変換ではメールアドレスの入力が必要です。

また、--build オプションを指定するとすべての po ファイルを mo ファイルに変換します。
この二つの処理を sphinx-gettext-helper が実行してくれることによって、gettext に関するコマンド操作が不要になります。


おすすめとしては Makefile を以下のように編集し、make gettext で一連の処理をすべて実行することです。

gettext:
        $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
        sphinx-gettext-helper -p $(BUILDDIR)/locale --update --build --statistics
        @echo
        @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."

このように書き換えると make clean gettext html コマンドを実行するだけで HTML 文書ができあがるため、
po ファイルの翻訳を行うことに集中することができます。

また、ここで指定している --statistics オプションは翻訳の状況を教えてくれます。
この表示を確認することで、見落としがちなあいまい(fuzzy)の項目を把握することができます。*2

$ sphinx-gettext-helper -p _build/locale --statistics
index.po: 2 個の翻訳メッセージ, 1 個の翻訳があいまいです, 1 個の未訳のメッセージ.

複数の言語に翻訳を行いたい場合

複数の言語に翻訳を行いたい場合、conf.py に language = 'ja' と書いてしまうと切り替えがしづらくなります。
その場合は以下のようにすることで、複数の言語に対応することができます。

1. conf.py から language の設定を削除する

実行オプションで設定を変更できるよう、language の設定を削除します。

2. Makefile を書き換える

Makefile の先頭付近の定義を以下のように書き換えます。

# You can set these variables from the command line.
LANGUAGE      = ja
SPHINXOPTS    = -D language=$(LANGUAGE)

gettext ターゲットに sphinx-gettext-helper を書き足している場合は、
その部分も合わせて書き換えましょう。

gettext:
        $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
        $(GETTEXTHELPER) -l $(LANGUAGE) -p $(BUILDDIR)/locale --update --build --statistics
        @echo
        @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
3. 実行する

make する際に言語を指定して実行します。

$ make LANGUAGE=en gettext html

こうすることで言語を切り替えながらドキュメントを生成することができます。

まとめ

sphinx-gettext-helper を使うと gettext 機能がすごく使いやすくなるよ!

実際に blockdiag.com のドキュメントは Sphinx + sphinx-gettext-helper を使って翻訳しています。
Jenkins を加えて HTML の自動ビルドも行っているので、
ドキュメント作成や翻訳だけに集中して作業することができるようになっています。

また、sphinx-gettext-helper に追加して欲しい機能があれば、是非 @tk0miya に連絡してください。

*1:オプションを調整することで片方だけにすることもできます。

*2:翻訳元の文章が変わったときは fuzzy フラグが立ちます