国際化¶
バージョン 1.1 で追加.
Sphinxで生成されたナビゲーションバーなどのメッセージが翻訳されるのに加え、Sphinxには ドキュメント の翻訳を容易にする機能があります。設定について詳しくは 国際化のオプション を参照してください。
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/"]
をセットします。出力したい形式でビルドします。
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.)
バージョン 4.5 で追加: The #noqa
mechanism.
sphinx-intlを使っての翻訳¶
クイックガイド¶
sphinx-intl は一連のSphinxの翻訳作業で使える有用なツールです。このセクションでは sphinx-intl を使った簡単な翻訳方法について説明します。
sphinx-intl をインストールします。
$ pip install sphinx-intl
conf.py
に設定を追加します:locale_dirs = ['locale/'] # path is example but recommended. gettext_compact = False # optional.
今回はBUILDDIRが
_build
にlocale_dirs
がlocale/
にgettext_compact
がFalse
に設定されていると仮定して進めます(Sphinx のドキュメントはそのように設定されています)。翻訳可能なメッセージを pot ファイルに展開します。
$ make gettext
生成されたpotファイルは
_build/gettext
ディレクトリに置かれます。poファイルを生成します。
上記の手順で生成されたpotファイルを使用します。
$ sphinx-intl update -p _build/gettext -l de -l ja
完了すると、生成されたpoファイルは次のディレクトリに配置されます。:
./locale/de/LC_MESSAGES/
./locale/ja/LC_MESSAGES/
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記法について、あなたを助けてくれるでしょう。
翻訳されたドキュメントを作成します。
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
ディレクトリに翻訳されたドキュメントが生成されました。
バージョン 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も簡単に実施してくれます。
Install transifex-client.
resources(pot ファイル) をアップロードするには tx コマンドが必要です。
$ pip install transifex-client
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/
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.
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.
Forward the translation on Transifex.
翻訳済みの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.
Login to Transifex service.
sphinx translation page に行きます。
Request language
をクリックし、フォームを埋めます。Wait acceptance by Transifex sphinx translation maintainers.
(After acceptance) Translate on Transifex.
Detail is here: https://docs.transifex.com/getting-started-1/translators
Translation progress and statistics¶
バージョン 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.
脚注