国際化

バージョン 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の 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/"] をセットします。

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

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

sphinx-intlを使っての翻訳

クイックガイド

sphinx-intl は Sphinx での翻訳フローで利用するのに便利なツールです。この節では sphinx-intl を利用して簡単に翻訳する方法について述べます。

  1. pip install sphinx-intleasy_install sphinx-intl を利用して sphinx-intl をインストールします。

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

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

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

  3. ドキュメントの翻訳可能なメッセージを pot ファイルに展開します。:

    $ make gettext
    

    As a result, many pot files are generated under _build/gettext directory.

  4. locale_dir 以下を初期設定 あるいは更新します:

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

    できました。ディレクトリの中にはpoファイルが出来てるはずです:

    • ./locale/de/LC_MESSAGES/
    • ./locale/ja/LC_MESSAGES/
  5. ./locale/<lang>/LC_MESSAGES/ 以下にある po ファイルを翻訳します。

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

    conf.pylanguage パラメーターを設定する必要があります、また、コマンドラインでもパラメータを設定できます:

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

おめでとうございます! _build/html ディレクトリに翻訳されたドキュメントが生成されました。

バージョン 1.3 で追加: make コマンド中で起動する sphinx-build が po ファイルより mo ファイルを生成します。

もし 1.2.x 以前を利用している場合、make の前に sphinx-intl build コマンドを実行してください。

翻訳

./locale/de/LC_MESSAGES ディレクトリ以下の po ファイルを翻訳します。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記法について、あなたを助けてくれるでしょう。

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

ドキュメントが更新された場合、更新された pot ファイルを生成し、翻訳した po ファイルに更新差分を適用する必要があります。pot ファイルの更新差分を適用するには sphinx-intl update コマンドを利用します。

$ sphinx-intl update -p _build/locale

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

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

  1. transifex-client のインストール

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

    $ pip install transifex-client
    
  2. transifex のアカウントを作成し、ドキュメント用に新規プロジェクトを作成します。

    現在のところ、transifexは1つの翻訳プロジェクトに複数のバージョンを持てません。そのため、プロジェクト名にバージョン番号を含めるのが良いでしょう。

    例:

    Project ID:sphinx-document-test_1_0
    Project 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ファイルをtransifexサーバーにアップロードします

    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ファイルを取得し、翻訳されたドキュメントを生成

    翻訳済みカタログを取得し、 moファイルを作成します (例: ‘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.
    

    make html コマンドを実行します:

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

以上です!

ちなみに

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

すべての言語のpoファイルをpushする場合 tx push -t コマンドを使用します。ただし、この操作はtransifex上の翻訳を上書きするので気を付けてください!

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

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

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

Sphinx-1.3 ドキュメントのために sphinx translation page があります。

  1. transifex にログインします。
  2. sphinx translation page に行きます。
  3. Request language をクリックし、フォームを埋めます。
  4. sphinx翻訳のメンテナーによって承認されるのを待ちます。
  5. (承認後)transifex上で翻訳します。

脚注

[1]このツール群の詳細については、 GNU gettextユーティリティ を参照してください。
[2]なぜなら誰もスペイン異端審問を期待していなからです!