国際化

Added in version 1.1.

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

../../_images/translation.svg

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

Sphinx 国際化について

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

Initially project maintainers have to collect all translatable strings (also referred to as messages) to make them known to translators. Sphinx extracts these through invocation of sphinx-build -M 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 オプションも使用できます)。

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

In order to protect against mistakes, a warning is emitted if cross-references in the translated paragraph do not match those from the original. This can be turned off globally using the suppress_warnings configuration variable. Alternatively, to turn it off for one message only, end the message with #noqa like this:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
risus tortor, luctus id ultrices at. #noqa

(Write \#noqa in case you want to have "#noqa" literally in the text. This does not apply to code blocks, where #noqa is ignored because code blocks do not contain references anyway.)

Added in version 4.5: The #noqa mechanism.

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ファイルを翻訳します。

    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. 翻訳されたドキュメントを作成します。

    conf.py には language パラメータが必要です。または、コマンドラインでパラメータを指定することもできます。

    For BSD/GNU make, run:

    $ 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 ディレクトリに翻訳されたドキュメントが生成されました。

Added in version 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/gettext

チームでの翻訳に 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.

    Currently, Transifex does not allow for a translation project to have more than one version of the document, so you'd better include a version number in your project name.

    例:

    プロジェクトの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. 翻訳済みの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

以上です!

Tip

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ファイルと、多くの時間とそれらを統合する労力がかかります。

Using Weblate service for team translation

Read more in Weblate's documentation.

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

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

There is a sphinx translation page for Sphinx (master) documentation.

  1. Login to Transifex service.

  2. sphinx translation page に行きます。

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

  4. Wait acceptance by Transifex sphinx translation maintainers.

  5. (After acceptance) Translate on Transifex.

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

Translation progress and statistics

Added in version 7.1.0.

During the rendering process, Sphinx marks each translatable node with a translated attribute, indicating if a translation was found for the text in that node.

The translation_progress_classes configuration value can be used to add a class to each element, depending on the value of the translated attribute.

The |translation progress| substitution can be used to display the percentage of nodes that have been translated on a per-document basis.

脚注