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 has two build options: -M and -b, use -b. Using -M creates a separate html folder under the output folder, which is inconvenient if you want to deploy it on the same site.
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.
Reference URL