国際化

バージョン 1.1 で追加.

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

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

    今回はBUILDDIRが _build に locale_dirs が locale/ に gettext_compact が False に設定されていると仮定して進めます(Sphinx のドキュメントはそのように設定されています)。

  3. 翻訳可能なメッセージを pot ファイルに展開します。

    $ make gettext

    生成されたpotファイルは _build/gettext ディレクトリに置かれます。

  4. poファイルを生成します。

    上記の手順で生成されたpotファイルを使用します。

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

    完了すると、生成されたpoファイルは次のディレクトリに配置されます。:

    • ./locale/de/LC_MESSAGES/

    • ./locale/ja/LC_MESSAGES/

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

  6. 翻訳されたドキュメントを作成します。

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

  5. transifexで翻訳を進めます。

  6. 翻訳済みの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.

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

  2. sphinx translation page に行きます。

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

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

  5. (After acceptance) Translate on transifex.

Detail is here: https://docs.transifex.com/getting-started-1/translators

脚注

1

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

2

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