sphinx translation procedure for users (draft)

sphinx-translation-procedure.rst

$ 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

  0. announce TRANSIFEX_USER/PW setup into ~/.trasifexrc if not exist
  1. sphinx-intl create/update resources for .tx/config source_file=_build/gettext/..., file_filter=$gettext_dir/<lang>/LC_...
  2. 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/