国際化

バージョン 1.1 で追加.

Sphinxで生成されたナビゲーションバーなどのメッセージが翻訳されるのに加え、Sphinxには ドキュメント そのものの翻訳を容易にする機能があります。設定について詳しくは 国際化のオプション を参照してください。

../../_images/translation.png

Sphinxによる翻訳のビジュアルなワークフロー(棒人間の絵は XKCD comic から借りました)

Sphinx 国際化について

gettext 1 は国際化とローカル化の手段として、よく使用されている方法です。プログラム中で使用されるメッセージと、翻訳文字列の対応表を使って置き換えてきます。Sphinxはこの機能を使って、ドキュメント全体を翻訳していきます。

まず最初に、プロジェクトのメンテナーはすべての翻訳文字列を集めてくる必要があります(これを メッセージ と呼ぶ)。これを翻訳者に渡します。Sphinxでは、 sphinx-build -b gettext を実行して、これを行います。

doctree中の要素一つごとにメッセージが一つ作られるので、doctreeと同じように分割されたかたまりのリストが得られます。大きななパラグラフは原文のように大きなまま残ります。これにより、ドキュメントの更新をシームレスにしつつ、翻訳者にコンテキスト情報を少し与えます。大きすぎるパラグラフを分割するのはメンテナーの役割で、自動化された方法はありません。

Sphinxの MessageCatalogBuilder の実行が完了すると、 .pot ファイル群が出力ディレクトリに出力されます。これらは カタログテンプレート と呼ばれ、元の言語のメッセージ のみ が含まれます。

これらのファイルを翻訳者に渡し、 メッセージカタログ と呼ばれる .po ファイルを作ってもらいます。これには、元のメッセージに対応する、外国語の文字列が書かれています。

gettext compiles them into a binary format known as binary catalogs through msgfmt for efficiency reasons. If you make these files discoverable with locale_dirs for your language, Sphinx will pick them up automatically.

An example: you have a document usage.rst in your Sphinx project. The gettext builder will put its messages into usage.pot. Imagine you have Spanish translations 2 stored in usage.po --- for your builds to be translated you need to follow these instructions:

  • メッセージカタログをコンパイルして、localeディレクトリに置きます。このディレクトリ名が locale だとすると、ソースディレクトリ内の ./locale/es/LC_MESSAGES/usage.mo という場所にバイナリカタログが置かれることになります( es はスペイン語の言語コード):

    msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"

  • locale_dirs に ["locale/"] をセットします。

  • language に es をセットします(-D オプションも使用できます)。

  • 出力したい形式でビルドします。

sphinx-intlを使っての翻訳

クイックガイド

sphinx-intl is a useful tool to work with Sphinx translation flow. This section describe an easy way to translate with sphinx-intl.

  1. Install sphinx-intl.

    $ pip install sphinx-intl

  2. Add configurations to conf.py.

    locale_dirs = ['locale/']   # path is example but recommended.
gettext_compact = False     # optional.

    This case-study assumes that locale_dirs is set to locale/ and gettext_compact is set to False (the Sphinx document is already configured as such).

  3. Extract translatable messages into pot files.

    $ make gettext

    The generated pot files will be placed in the _build/gettext directory.

  4. Generate po files.

    We'll use the pot files generated in the above step.

    $ sphinx-intl update -p _build/gettext -l de -l ja

    Once completed, the generated po files will be placed in the below directories:

    • ./locale/de/LC_MESSAGES/

    • ./locale/ja/LC_MESSAGES/

  5. Translate po files.

    AS noted above, these are located in the ./locale/<lang>/LC_MESSAGES directory. An example of one such file, from Sphinx, builders.po, is given below.

    # 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記法について、あなたを助けてくれるでしょう。

  6. Build translated document.

    You need a language parameter in conf.py or you may also specify the parameter on the command line.

    For for BSD/GNU make, run:

    $ make -e SPHINXOPTS="-D language='de'" html

    For Windows cmd.exe, run:

    > 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 で追加: sphinx-build that is invoked by make command will build po files into mo files.

If you are using 1.2.x or earlier, please invoke sphinx-intl build command before make command.

poファイルを新しいpotファイルで置き換えます。

If a document is updated, it is necessary to generate updated pot files and to apply differences to translated po files. In order to apply the updates from a pot file to the po file, use the sphinx-intl update command.

$ sphinx-intl update -p _build/locale

チームでの翻訳に Transifex サービスを利用する

Transifex はウェブインターフェースを通して共同作業で翻訳することを可能にするサービスの一つです。 Pythonベースの気のきいたコマンドラインクライアントもあり、翻訳の取得やpushも簡単に実施してくれます。

  1. Install transifex-client.

    resources(pot ファイル) をアップロードするには tx コマンドが必要です。

    $ pip install transifex-client

    参考

    Transifex Client documentation

  2. 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/

  3. Create config files for tx command.

    ここの処理では現在のディレクトリに .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.

  4. Upload pot files to transifex service.

    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.

  5. Forward the translation on transifex.

  6. Pull translated po files and make translated HTML.

    Get translated catalogs and build mo files. For example, to build mo files for German (de):

    $ 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.

    Invoke make html (for BSD/GNU make):

    $ make -e SPHINXOPTS="-D language='de'" html

以上です!

ちなみに

Transifex上での翻訳およびローカルでの翻訳

If you want to push all language's po files, you can be done by using tx push -t command. Watch out! This operation overwrites translations in transifex.

つまり、更新する各サービスとローカルpoファイルと、多くの時間とそれらを統合する労力がかかります。

Sphinxリファレンスの翻訳に貢献する

Sphinxリファレンスの翻訳に新しく加わりたい人にお勧めする方法は、Transifex上の翻訳チームに参加することです。

Sphinx (master) ドキュメント用の sphinx translation page があります。

  1. transifex にログインします。

  2. sphinx translation page に行きます。

  3. Request language をクリックし、フォームを埋めます。

  4. sphinx翻訳のメンテナーによって承認されるのを待ちます。

  5. (After acceptance) Translate on transifex.

脚注

1

このツール群の詳細については、 GNU gettextユーティリティ を参照してください。

2

まさかの時のスペイン宗教裁判！(訳注：「モンティ・パイソン」のセリフ)