Edited at

Sphinxでドキュメントを国際化

More than 3 years have passed since last update.

GitHubやらのリポジトリにpushした時にbuildしてドキュメントを公開する、という設定です。


Sphinxのインストール

このページの通りにやる。


sphinx-quickstart などの後の作業


sphinx-intl をインストール

$ sudo pip install sphinx-intl


conf.py編集

以下を追記

locale_dirs = ["locale"]


potファイル作成

$ make gettext

_build/locale にpotファイルが出来る


locale/pot にコピー

$ mkdir locale/pot  # 2度目以降不要

$ cp -R _build/locale/*.pot locale/pot/


各言語のディレクトリにコピー

$ mkdir -p locale/ja/LC_MESSAGES  # 2度目以降不要

$ cp -R locale/pot/* locale/ja/LC_MESSAGES/


翻訳用のpoファイル作成

$ sphinx-intl update -p _build/locale -l ja


poファイルに翻訳文を書き込む

locale/ja/LC_MESSAGES にあるpoファイルに翻訳文を書き込む。

    msgid "Sphinx"

msgstr ""

の msgstr "" に翻訳文を書いていく。



    msgstr "スフィンクス"



poファイルからmoファイルを作成

以下はpushしてJenkinsにやらせる。(自分でmoファイルを作成しても良いけど。)

$ sphinx-intl build


moファイルからhtml作成

$ make clean html

cleanを付けておかないと、作成されたhtml中で、追加したドキュメントに対するドキュメント内参照(:doc:)のリンクが有効にならないので、cleanを付けてます。


ドキュメント更新後

$ make gettext

以降をもう一度やる。


Jenkinsでシェルの実行

上記の通りで、翻訳文を追加するとこまでを人がやれば良いので、push後にやって欲しい作業は

$ sphinx-intl build

$ make clean html


ドキュメントの公開

ドキュメントの公開は、ビルドするJenkinsのジョブとは別にジョブを作成し、ビルド後にドキュメントを公開するようにする。詳細は省略。


余談

毎回コマンドを打つのが面倒なので、shell scriptに以下の様に書いておくと便利。


translate.sh

make gettext

cp -R _build/locale/*.pot locale/pot/
cp -R locale/pot/* locale/ja/LC_MESSAGES/
sphinx-intl update -p _build/locale -l ja



翻訳をする


build.sh

sphinx-intl build

make clean html


Tips


インデント

.. toctree::

:maxdepth: 1

top
document1
document2

topとかdocument1の部分は、スペース3つでインデントしないとエラーになる。


locale

ValueError: unknown locale: UTF-8

のエラーについて。

"LC_ALL=" が空になっているのが原因。

$ locale

LANG=
LC_COLLATE="C"
LC_CTYPE="UTF-8"
LC_MESSAGES="C"
LC_MONETARY="C"
LC_NUMERIC="C"
LC_TIME="C"
LC_ALL=

$ export LC_ALL='ja_JP.UTF-8'

$ locale

LANG=
LC_COLLATE="ja_JP.UTF-8"
LC_CTYPE="ja_JP.UTF-8"
LC_MESSAGES="ja_JP.UTF-8"
LC_MONETARY="ja_JP.UTF-8"
LC_NUMERIC="ja_JP.UTF-8"
LC_TIME="ja_JP.UTF-8"
LC_ALL="ja_JP.UTF-8"

これで、解決。

export LC_ALL='ja_JP.UTF-8'

をbashrcに書き込む

$ vi ~/.bashrc

$ source ~/.bashrc


参考