sphinx translation procedure for users (draft)

$ pip install sphinx[intl]

$ sphinx-quickstart

wizard: translations
wizard: language

edit conf.py (optional):
- add translations
- set language

pseudo code:

gettext_dir = config.gettext_dir or "locale"
locale_dirs = config.locale_dirs or [gettext_dir]

case: if user : locale_dirs = ["translations"]; gettext_dir = "":

gettext_dir = "locale"
locale_dirs = ["sphinx_translation", gettext_dir]

write reST files

$ make gettext

generate pot into _build/locale or _build/gettext.
if transifex extension enabled:
- automatically do sphinx-intl tx-push
sphinx-intl tx-push
1. announce TRANSIFEX_USER/PW setup into ~/.trasifexrc if not exist
2. sphinx-intl create/update resources for .tx/config source_file=_build/gettext/..., file_filter=$gettext_dir/<lang>/LC_...
3. cd to-contain-.tx && tx push -s

translate po files on the transifex

make html

for single lang with translations=[] and `language="de" in conf.py:

$ tx pull -l de
$ make html
   * build mo files in `gettext_dir` if mo files are outdeted
   * make html    => _build/html/

for single lang with translations=[] in conf.py, and --force-translation:

$ tx pull -l de
$ make html  SPHINXOPTS=--language=de or SPHINXLANG=de or config.language="de"
   * build mo files in `gettext_dir` if mo files are outdeted
   * make html    => _build/html/de/

for single lang with translations=["de", "ja"] in conf.py:

$ tx pull -l de
$ make html  SPHINXOPTS=--language=de or SPHINXLANG=de
   * build mo files in `gettext_dir` if mo files are outdeted
   * make html    => _build/html/de/

for all langs with translations=["de", "ja"] in conf.py:

$ tx pull
$ make html   # build all html for `translations` + `language` values
   for lang in `translations + language`:
       make html --language=lang    => _build/html/$lang/

shimizukawa/sphinx-translation-procedure.rst