国際化¶
バージョン 1.1 で追加.
Sphinxで生成されたナビゲーションバーなどのメッセージが翻訳されるのに加え、Sphinxには ドキュメント の翻訳を容易にする機能があります。設定について詳しくは 国際化のオプション を参照してください。
Sphinx 国際化について¶
gettext 1 は国際化とローカル化の手段として、よく使用されている方法です。プログラム中で使用されるメッセージと、翻訳文字列の対応表を使って置き換えてきます。Sphinxはこの機能を使って、ドキュメント全体を翻訳していきます。
まず最初に、プロジェクトのメンテナーはすべての翻訳文字列を集めてくる必要があります(これを メッセージ と呼ぶ)。これを翻訳者に渡します。Sphinxでは、 sphinx-build -b gettext
を実行して、これを行います。
doctree中の要素一つごとにメッセージが一つ作られるので、doctreeと同じように分割されたかたまりのリストが得られます。大きななパラグラフは原文のように大きなまま残ります。これにより、ドキュメントの更新をシームレスにしつつ、翻訳者にコンテキスト情報を少し与えます。大きすぎるパラグラフを分割するのはメンテナーの役割で、自動化された方法はありません。
Sphinxの MessageCatalogBuilder
の実行が完了すると、 .pot
ファイル群が出力ディレクトリに出力されます。これらは カタログテンプレート と呼ばれ、元の言語のメッセージ のみ が含まれます。
これらのファイルを翻訳者に渡し、 メッセージカタログ と呼ばれる .po
ファイルを作ってもらいます。これには、元のメッセージに対応する、外国語の文字列が書かれています。
gettext の msgfmt コマンドを使い、バイナリ形式で効率良い バイナリカタログ にコンパイルします。 language
オプションと、 locale_dirs
設定の場所にこれらのバイナリカタログを置くと、Sphinxはこれらのファイルを読み込んで使用します。
例: Sphinxプロジェクト内に usage.rst
というドキュメントがあるとします。gettext ビルダーは文章を usage.pot
に書き出します。 usage.po
のスペイン語翻訳 2 があるとしましょう。 --- 翻訳されたドキュメントをビルドするには以下のようにする必要があります。
メッセージカタログをコンパイルして、localeディレクトリに置きます。このディレクトリ名が
locale
だとすると、ソースディレクトリ内の./locale/es/LC_MESSAGES/usage.mo
という場所にバイナリカタログが置かれることになります(es
はスペイン語の言語コード):msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"
locale_dirs
に["locale/"]
をセットします。出力したい形式でビルドします。
sphinx-intlを使っての翻訳¶
クイックガイド¶
sphinx-intl は一連のSphinxの翻訳作業で使える有用なツールです。このセクションでは sphinx-intl を使った簡単な翻訳方法について説明します。
sphinx-intl をインストールします。
$ pip install sphinx-intl
conf.py
に設定を追加します:locale_dirs = ['locale/'] # path is example but recommended. gettext_compact = False # optional.
今回はBUILDDIRが
_build
にlocale_dirs
がlocale/
にgettext_compact
がFalse
に設定されていると仮定して進めます(Sphinx のドキュメントはそのように設定されています)。翻訳可能なメッセージを pot ファイルに展開します。
$ make gettext
生成されたpotファイルは
_build/gettext
ディレクトリに置かれます。poファイルを生成します。
上記の手順で生成されたpotファイルを使用します。
$ sphinx-intl update -p _build/gettext -l de -l ja
完了すると、生成されたpoファイルは次のディレクトリに配置されます。:
./locale/de/LC_MESSAGES/
./locale/ja/LC_MESSAGES/
poファイルを翻訳します。
上記のように、これらは
./locale/<lang>/LC_MESSAGES
ディレクトリにあります。Sphinxのbuilders.po
のこのようなファイルの例を以下に示します。# a5600c3d2e3d48fc8c261ea0284db79b #: ../../builders.rst:4 msgid "Available builders" msgstr "<FILL HERE BY TARGET LANGUAGE>"
別の場合として、msgid が複数行のテキストで reStructuredText の構文を含む場合:
# 302558364e1d41c69b3277277e34b184 #: ../../builders.rst:9 msgid "" "These are the built-in Sphinx builders. More builders can be added by " ":ref:`extensions <extensions>`." msgstr "" "FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE " "BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."
reST記法を崩さないよう、注意して下さい。ほとんどのpoエディタがreST記法について、あなたを助けてくれるでしょう。
翻訳されたドキュメントを作成します。
conf.py
にはlanguage
パラメータが必要です。または、コマンドラインでパラメータを指定することもできます。BSD/GNU makeの場合、次のコマンドを実行します。
$ make -e SPHINXOPTS="-D language='de'" html
Windows cmd.exe の場合、次のコマンドを実行します。
> set SPHINXOPTS=-D language=de > .\make.bat html
For PowerShell, run:
> Set-Item env:SPHINXOPTS "-D language=de" > .\make.bat html
おめでとうございます! _build/html
ディレクトリに翻訳されたドキュメントが生成されました。
バージョン 1.3 で追加: make コマンド中で起動する sphinx-build が po ファイルより mo ファイルを生成します。
もし 1.2.x 以前を利用している場合、 make の前に sphinx-intl build コマンドを実行してください。
poファイルを新しいpotファイルで置き換えます。¶
もしドキュメントがアップデートされたら、アップデートされた potファイルを再度生成し翻訳済みpoファイルへ更新を適用する必要があります。potファイルのアップデート差分をpoファイルへ適用するには、 sphinx-intl update コマンドを利用します。
$ sphinx-intl update -p _build/locale
チームでの翻訳に Transifex サービスを利用する¶
Transifex はウェブインターフェースを通して共同作業で翻訳することを可能にするサービスの一つです。 Pythonベースの気のきいたコマンドラインクライアントもあり、翻訳の取得やpushも簡単に実施してくれます。
Install transifex-client.
resources(pot ファイル) をアップロードするには tx コマンドが必要です。
$ pip install transifex-client
Create your transifex account and create new project for your document.
現在のところ、transifexは1つの翻訳プロジェクトに複数のバージョンを持てません。そのため、プロジェクト名にバージョン番号を含めるのが良いでしょう。
例:
- プロジェクトのID
sphinx-document-test_1_0
- プロジェクトのURL
https://www.transifex.com/projects/p/sphinx-document-test_1_0/
tx コマンドのために設定ファイルを作成します
ここの処理では現在のディレクトリに
.tx/config
ディレクトリと、認証情報を含む~/.transifexrc
というファイルを作成します。$ tx init Creating .tx folder... Transifex instance [https://www.transifex.com]: ... Please enter your transifex username: <transifex-username> Password: <transifex-password> ... Done.
potファイルをtransfexサービスにアップロードします。
potファイルを
.tx/config
ファイルに登録します:$ cd /your/document/root $ sphinx-intl update-txconfig-resources --pot-dir _build/locale \ --transifex-project-name sphinx-document-test_1_0
そして、potファイルをアップロードします:
$ tx push -s Pushing translations for resource sphinx-document-test_1_0.builders: Pushing source file (locale/pot/builders.pot) Resource does not exist. Creating... ... Done.
transifexで翻訳を進めます。
翻訳済みのpoファイルを取得し、翻訳されたHTMLを生成
変換されたカタログを取得し、moファイルを構築します。たとえば、ドイツ語 (de) 用のmoファイルをビルドするには、次のように指定します。
$ cd /your/document/root $ tx pull -l de Pulling translations for resource sphinx-document-test_1_0.builders (...) -> de: locale/de/LC_MESSAGES/builders.po ... Done.
(BSDやGNUのmakeで) make html コマンドを実行します:
$ make -e SPHINXOPTS="-D language='de'" html
以上です!
ちなみに
Transifex上での翻訳およびローカルでの翻訳
すべての言語のpoファイルをpushする場合 tx push -t を使用します。ただし、この操作はtransifex上の翻訳を上書きするので気を付けてください!
つまり、更新する各サービスとローカルpoファイルと、多くの時間とそれらを統合する労力がかかります。
Sphinxリファレンスの翻訳に貢献する¶
Sphinxリファレンスの翻訳に新しく加わりたい人にお勧めする方法は、Transifex上の翻訳チームに参加することです。
There is a sphinx translation page for Sphinx (master) documentation.
transifex にログインします。
sphinx translation page に行きます。
Request language
をクリックし、フォームを埋めます。sphinx翻訳のメンテナーによって承認されるのを待ちます。
(After acceptance) Translate on transifex.
Detail is here: https://docs.transifex.com/getting-started-1/translators
脚注
- 1
このツール群の詳細については、 GNU gettextユーティリティ を参照してください。
- 2
まさかの時のスペイン宗教裁判!(訳注:「モンティ・パイソン」のセリフ)