国際化

バージョン 1.1 で追加.

Complementary to translations provided for Sphinx-generated messages such as navigation bars, Sphinx provides mechanisms facilitating the translation of documents. See the 国際化のオプション for details on configuration.

../../_images/translation.svg

Sphinxでのワークフローによる翻訳の可視化(この図形は plantuml によって作成されました)。

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/"] をセットします。

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

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

sphinx-intlを使っての翻訳

クイックガイド

sphinx-intl は一連のSphinxの翻訳作業で使える有用なツールです。このセクションでは sphinx-intl を使った簡単な翻訳方法について説明します。

  1. sphinx-intl をインストールします。

    $ pip install sphinx-intl

  2. conf.py に設定を追加します:

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

    This case-study assumes that BUILDDIR is set to _build, 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.

    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も簡単に実施してくれます。

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

  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

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