国際化

Added in version 1.1.

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

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はこれらのファイルを読み込んで使用します。

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:

• Compile your message catalog to a locale directory, say locale, so it ends up in ./locale/es/LC_MESSAGES/usage.mo in your source directory (where es is the language code for Spanish.)

  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. Add configurations to 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
   

   The generated pot files will be placed in the _build/gettext directory. If you want to customize the output beyond what can be done via the Options for internationalisation, the default pot file template can be replaced by a custom message.pot.jinja file placed in any directory listed in templates_path.

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

   Please be careful not to break reStructuredText notation. Most po-editors will help you with that.

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

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

   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:

   PS> Set-Item env:SPHINXOPTS "-D language=de"
   PS> .\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 is one of several services that allow collaborative translation via a web interface. It has a nifty Go-based command line client that makes it easy to fetch and push translations.

1. Install the Transifex CLI tool.

   You need the tx command line tool for uploading resources (pot files). The official installation process place the tx binary file in the current directory along with a README and a LICENSE file, and adds the current directory to $PATH.

   $ curl -o- https://raw.githubusercontent.com/transifex/cli/master/install.sh | bash
   

   参考

   Transifex Client documentation

2. Create your Transifex account and create a new project and an organization 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.

   例:

   Organization ID:

   sphinx-document

   プロジェクトのID:

   sphinx-document-test_1_0

   プロジェクトのURL:

   https://www.transifex.com/projects/p/sphinx-document-test_1_0/

3. Create an API token to be used in the command-line.

   Go to your Transifex API token page and generate a token. Copy the generated token now, as you will not be able to see it again later.

4. Set your Transifex API token in the user configuration file $HOME/.transifexrc.

   [https://app.transifex.com]
   rest_hostname = https://rest.api.transifex.com
   token         = paste_your_api_token_here
   

5. Alternatively, you can store your Transifex API token as the environment variable TX_TOKEN, which is recognized and used by tx.

   $ export TX_TOKEN=paste_your_api_token_here
   

6. Create the project's config file for tx command.

   This process will create .tx/config in the current directory.

   $ cd /your/document/root
   $ tx init
   
   Successful creation of '.tx/config' file
   

7. Upload pot files to Transifex service.

   Register pot files to .tx/config file using sphinx-intl update-txconfig-resources, adjusting --pot-dir value to your project's pot files' directory:

   $ cd /your/document/root
   $ sphinx-intl update-txconfig-resources --pot-dir _build/locale \
     --transifex-organization-name=sphinx-document \
     --transifex-project-name=sphinx-document-test_1_0
   

   You can use the SPHINXINTL_TRANSIFEX_ORGANIZATION_NAME and SPHINXINTL_TRANSIFEX_PROJECT_NAME environment variables instead of the respective command line arguments.

   参考

   sphinx-intl update-txconfig-resources documentation

   そして、potファイルをアップロードします:

   $ tx push -s
   # Getting info about resources
   
   sphinx-document-test_1_0.builders - Getting info
   sphinx-document-test_1_0.builders - Done
   
   # Pushing source files
   
   sphinx-document-test_1_0.builders - Uploading file
   sphinx-document-test_1_0.builders - Done
   

8. Forward the translation on Transifex.

9. 翻訳済みのpoファイルを取得し、翻訳されたHTMLを生成

   変換されたカタログを取得し、moファイルを構築します。たとえば、ドイツ語 (de) 用のmoファイルをビルドするには、次のように指定します。

   $ cd /your/document/root
   $ tx pull -l de
   # Getting info about resources
   
   sphinx-document-test_1_0.builders - Getting info
   sphinx-document-test_1_0.builders - Done
   
   # Pulling files
   
   sphinx-document-test_1_0.builders [de] - Pulling file
   sphinx-document-test_1_0.builders [de] - Creating download job
   sphinx-document-test_1_0.builders [de] - Done
   

   Invoke make html (for BSD/GNU make) passing the language code:

   $ 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. Go to the "Sphinx's documentation" translation project.

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

4. Wait acceptance by Transifex sphinx translation maintainers.

5. (After acceptance) Translate on Transifex.

Detail is here: https://help.transifex.com/en/articles/6248698-getting-started-as-a-translator

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.

脚注

[1]

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

[2]

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

Previous

HTML theming

Next

Sphinxウェブサポート