Multilingual Support for Sphinx Documentation#
- Update:
2023-05-05
Note
The execution environment is Windows10
1. Install Required Packages#
pip install sphinx
pip install sphinx-intl
2. Create a Sphinx Project#
sphinx-quickstart
3. Open the conf.py File and Add/Modify Language and Locale Settings#
First, add language settings and specify the default language. For example, if you want to set Japanese as your default language, do the following:
# conf.py
language = 'ja'
Next, add settings for other languages. Create dedicated directories for each language and store translated documents inside them.
# conf.py
locale_dirs = ['locale/']
gettext_compact = False
4. Generate a .pot File for the Default Language#
make.bat gettext
Tip
pot stands for Potable Object Template
5. Convert the Generated .pot File to .po Files for Each Language.#
If targeting English, Spanish, Arabic and German, describe as follows.
sphinx-intl update -p _build/gettext -l en -l es -l ar -l de
Tip
The PO in a .po file stands for Portable Object,while MO in a .mo file stands for Machine Object
6. Edit the .po file to add translations.#
For example, open locale/ja/LC_MESSAGES/index.po and add Japanese translation.
7. Build translated document.#
sphinx-build -b html . _build/html/ja
sphinx-build -b html . _build/html/en -D language=en
sphinx-build -b html . _build/html/es -D language=es
sphinx-build -b html . _build/html/ar -D language=ar
sphinx-build -b html . _build/html/de -D language=de
Tip
sphinx-build のビルドオプションは -M と -b があり、-b を使う。-M を用いるとoutputフォルダの下に独自にhtmlフォルダが作成されるため同じサイトにデプロイしたい場合には不便。
8. Make sure the built HTML files for each language are stored in the _build/html directory.#
With this, you can create documentation that supports multiple languages using Sphinx. To add links and navigation between languages, you will need to customize the templates.
参考URL