国際化¶
バージョン 1.1 で追加.
ナビゲーションバーのような Sphinx で生成されたメッセージに提供される翻訳を補完するために、Sphinx は *ドキュメント* の翻訳を容易にするメカニズムを提供します。 設定の詳細については、国際化のオプションを参照してください。
Sphinx 国際化の詳細¶
gettext [1] は国際化およびローカリゼーションのための確立された標準です。これは、プログラム内のメッセージを翻訳された文字列に単純にマッピングします。Sphinx は、これらの機能を使用してドキュメント全体を翻訳します。
最初に、プロジェクトのメンテナーは、翻訳者が認識できるように、翻訳可能なすべての文字列（*メッセージ* とも呼ばれます）を収集する必要があります。 Sphinx は、sphinx-build -M gettext の呼び出しを通じてこれらを抽出します。
ドクトリー内のすべての要素は単一のメッセージで終わります。これにより、リストは異なるチャンクに均等に分割されますが、大きな段落は元のドキュメントと同じように粗く分割されたままになります。これにより、翻訳者が自由形式の文章で少しばかりのコンテキストを提供しながら、シームレスなドキュメントの更新が可能になります。段落が大きすぎる場合、それを分割するのはメンテナーの仕事です。そのため、自動化された適切な方法は存在しません。
Sphinx が MessageCatalogBuilder を正常に実行すると、出力ディレクトリに .pot ファイルのコレクションが見つかります。これらは *カタログテンプレート* であり、元の言語のメッセージ *のみ* が含まれています。
これらは翻訳者に配信でき、翻訳者は、元のメッセージから外国語の文字列へのマッピングを含む、いわゆる *メッセージカタログ* である .po ファイルに変換します。
効率上の理由から、*gettext* は msgfmt を介してこれらを *バイナリカタログ* と呼ばれるバイナリ形式にコンパイルします。これらのファイルを locale_dirs を使用して language に対して検出可能にすると、Sphinx はそれらを自動的に取得します。
例: Sphinx プロジェクトに usage.rst ドキュメントがあるとします。 *gettext* ビルダーは、そのメッセージを usage.pot に入れます。 スペイン語の翻訳 [2] が usage.po に保存されていると想像してください。翻訳されたビルドを行うには、次の手順に従う必要があります。
メッセージカタログをロケールディレクトリ（たとえば
locale）にコンパイルして、ソースディレクトリの./locale/es/LC_MESSAGES/usage.moに配置します（esはスペイン語の言語コードです）。msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"
locale_dirsを["locale/"]に設定します。目的のビルドを実行します。
誤りを防ぐために、翻訳された段落内の相互参照が元の段落と一致しない場合、警告が発行されます。これは、suppress_warnings 構成変数を使用してグローバルにオフにできます。または、1 つのメッセージのみに対してオフにするには、次のようにメッセージを #noqa で終わらせます。
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
risus tortor, luctus id ultrices at. #noqa
（テキスト内に「#noqa」を文字どおりに含める場合は、\#noqa と記述します。これは、コードブロックには適用されません。コードブロックには参照が含まれていないため、#noqa は無視されます。）
バージョン 4.5 で追加: #noqa メカニズム。
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ディレクトリに配置されます。 国際化のオプション を介して実行できる範囲を超えて出力をカスタマイズする場合は、デフォルト pot ファイル テンプレートをtemplates_pathにリストされている任意のディレクトリに配置されたカスタムmessage.pot.jinjaファイルで置き換えることができます。po ファイルを生成します。
上記の手順で生成された pot ファイルを使用します。
$ sphinx-intl update -p _build/gettext -l de -l ja
完了すると、生成された po ファイルは以下のディレクトリに配置されます。
./locale/de/LC_MESSAGES/./locale/ja/LC_MESSAGES/
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."
reStructuredText 表記を壊さないように注意してください。ほとんどの po エディターはそれを支援します。
翻訳されたドキュメントをビルドします。
conf.pyにlanguageパラメーターが必要です。または、コマンドラインでパラメーターを指定することもできます。BSD/GNU make の場合は、次を実行します。
$ make -e SPHINXOPTS="-D language='de'" html
Windows cmd.exe の場合は、次を実行します。
> set SPHINXOPTS=-D language=de > .\make.bat html
PowerShell の場合は、次を実行します。
PS> Set-Item env:SPHINXOPTS "-D language=de" PS> .\make.bat html
おめでとうございます！ _build/html ディレクトリに翻訳されたドキュメントがあります。
バージョン 1.3 で追加: make コマンドによって呼び出される sphinx-build は、po ファイルを mo ファイルにビルドします。
1.2.x 以前を使用している場合は、make コマンドの前に sphinx-intl build コマンドを呼び出してください。
翻訳¶
新しい pot ファイルで po ファイルを更新¶
ドキュメントが更新された場合、更新された pot ファイルを生成し、翻訳された po ファイルに差分を適用する必要があります。 pot ファイルからの更新を po ファイルに適用するには、sphinx-intl update コマンドを使用します。
$ sphinx-intl update -p _build/gettext
チーム翻訳のための Transifex サービスの使用¶
Transifex は、Web インターフェイスを介した共同翻訳を可能にするいくつかのサービスのうちの 1 つです。翻訳の取得とプッシュを容易にする、優れた Go ベースのコマンドラインクライアントがあります。
Transifex CLI ツールをインストールします。
リソース（pot ファイル）をアップロードするには、tx コマンドラインツールが必要です。公式のインストールプロセスでは、
txバイナリファイルが README および LICENSE ファイルとともに現在のディレクトリに配置され、現在のディレクトリが$PATHに追加されます。$ curl -o- https://raw.githubusercontent.com/transifex/cli/master/install.sh | bash
こちらも参照
Transifex アカウントを作成し、ドキュメントの新しいプロジェクトと組織を作成します。
現在、Transifex では、翻訳プロジェクトがドキュメントの複数のバージョンを持つことは許可されていないため、プロジェクト名にバージョン番号を含めることをお勧めします。
例
- 組織 ID:
sphinx-document- プロジェクト ID:
sphinx-document-test_1_0- プロジェクトURL:
https://www.transifex.com/projects/p/sphinx-document-test_1_0/
コマンドラインで使用するAPIトークンを作成します。
Transifex APIトークンページに移動し、トークンを生成します。生成されたトークンは後で再度表示できないため、今すぐコピーしてください。
Transifex APIトークンをユーザー設定ファイル
$HOME/.transifexrcに設定します。[https://app.transifex.com] rest_hostname = https://rest.api.transifex.com token = paste_your_api_token_here
または、Transifex APIトークンを環境変数
TX_TOKENとして保存することもできます。これはtxによって認識され、使用されます。$ export TX_TOKEN=paste_your_api_token_here
txコマンド用のプロジェクト設定ファイルを作成します。
このプロセスにより、現在のディレクトリに
.tx/configが作成されます。$ cd /your/document/root $ tx init Successful creation of '.tx/config' file
potファイルをTransifexサービスにアップロードします。
.tx/configファイルにpotファイルを登録します。sphinx-intl update-txconfig-resourcesを使用し、--pot-dirの値をプロジェクトのpotファイルディレクトリに合わせて調整します。$ 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
コマンドライン引数の代わりに、環境変数
SPHINXINTL_TRANSIFEX_ORGANIZATION_NAMEとSPHINXINTL_TRANSIFEX_PROJECT_NAMEを使用できます。そして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
Transifexで翻訳を転送します。
翻訳された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
言語コードを渡してmake html（BSD/GNU makeの場合）を呼び出します。
$ make -e SPHINXOPTS="-D language='de'" html
以上です！
ヒント
ローカルおよびTransifexでの翻訳
すべての言語のpoファイルをプッシュする場合は、tx push -tコマンドを使用することで実行できます。注意してください！この操作はTransifexの翻訳を上書きします。
言い換えれば、サービスとローカルのpoファイルをそれぞれ更新した場合、それらを統合するには多くの時間と労力がかかります。
チーム翻訳にWeblateサービスを使用する¶
Weblateのドキュメントで詳細をご覧ください。
Sphinxリファレンス翻訳への貢献¶
新しい貢献者がSphinxリファレンスを翻訳する推奨される方法は、Transifexの翻訳チームに参加することです。
Sphinx（master）ドキュメント用のsphinx翻訳ページがあります。
Transifexサービスにログインします。
sphinx翻訳ページに移動します。
言語をリクエストをクリックし、フォームに入力します。Transifex sphinx翻訳メンテナーによる承認を待ちます。
（承認後）Transifexで翻訳します。
詳細はこちら：https://help.transifex.com/en/articles/6248698-getting-started-as-a-translator
翻訳の進捗状況と統計¶
バージョン7.1.0で追加されました。
レンダリングプロセス中、Sphinxは翻訳可能な各ノードをtranslated属性でマークし、そのノードのテキストの翻訳が見つかったかどうかを示します。
translation_progress_classes構成値を使用して、translated属性の値に応じて、各要素にクラスを追加できます。
|翻訳進捗|代替を使用して、ドキュメントごとに翻訳されたノードの割合を表示できます。
脚注