Writing multi-language Documentation using Sphinx Markus Zapke-Gründemann Write The Docs Europe 2014 

Markus Zapke-Gründemann Software Developer since 2001 Python, Django, Open Data and Training Independent since 2008 Owner of transcode keimlink.de // @keimlink 

Basics 

Sphinx Python Documentation Generator Markup Language: reStructuredText Output Formats: HTML, LaTeX (PDF), ePub, Texinfo, manual pages, plain text sphinx-doc.org 

Internationalization Often referred to as i18n Translating into other languages without changing the code GNU gettext is used frequently 

gettext Example import gettext t = gettext.translation('example', 'locale', fallback=True) _ = t.ugettext print _('Write the Docs') 

Sphinx Internationalization 

Sphinx i18n Workflow Source: http://sphinx-doc.org/intl.html 

Sphinx i18n
Configuration docs/conf.py language = 'en' locale_dirs = ['locale/'] # New in version 1.1 gettext_compact = True 

Sphinx i18n
Process $ make gettext $ msginit --no-translator -l de_DE \ -i _build/locale/setup.pot \ -o locale/de/LC_MESSAGES/setup.po # Translate documentation $ msgfmt --check-format \ -D locale/de/LC_MESSAGES setup.po \ -o locale/de/LC_MESSAGES/setup.mo $ make SPHINXOPTS="-Dlanguage=de" html 

No content

sphinx-intl $ pip install sphinx-intl https://pypi.python.org/pypi/sphinx-intl 

sphinx-intl $ make gettext $ sphinx-intl update -l de -p _build/locale # Translate documentation $ sphinx-intl build $ make SPHINXOPTS="-Dlanguage=de" html 

Transifex 

www.transifex.com 

Transifex Setup $ pip install transifex-client $ tx init --user= --pass= 

Transifex and sphinx-intl $ sphinx-intl update-txconfig-resources \ --pot-dir _build/locale \ --transifex-project-name $ tx push -s # Translate documentation on Transifex $ tx pull -l de $ sphinx-intl build $ make SPHINXOPTS="-Dlanguage=de" html 

Handy tips for translating Sphinx documentation 

Using code inside the documentation All text inside the code should be English: ! class Bookmark(models.Model): url = models.URLField() title = models.CharField('title', max_length=255) description = models.TextField('description', blank=True) 

How to handle URLs Always use the inline syntax: ! Alternatively, you can get the `Python Sources `_ from the website and compile it yourself. ! Because this way the URL will get lost: ! Alternatively, you can get the `Python Sources`_ from the website and compile it yourself. ! .. _Python Sources: http://python.org/download/ 

How to maintain versoined URLs You can use the extlinks extension to define URLs in the configuration: ! extlinks = { 'djangodocs': ('https://docs.djangoproject.com/en/1.5/%s', None), 'djangopdf': ('http://media.readthedocs.org/pdf/django/1.5.x/django.pdf%s', None) } ! You can find a list of all ``QuerySet`` methods in the :djangodocs:`documentation `. ! Download the :djangopdf:`Django Offline PDF Documentation <>` which has currently more than 1,200 pages. 

How to handle special cases ifconfig can be used to handle special cases: ! .. ifconfig:: language == 'de' ! Nützliche Links für deutschsprachige Django-Nutzer: ! - `Deutschsprachige Django-Community `_ 

Link checking You can check the links for each language separately: ! $ make SPHINXOPTS="-Dlanguage=de" linkcheck 

What is still missing? It’s not possible to build all languages at once A way to add a „landing page“ A translations setting Use gettext_compact to create a single catalog A language switch template 

Sphinx 1.3 Merge sphinx-intl into Sphinx Move Transifex support from sphinx-intl to a new extension Allow to build all languages with a single command 

Thanks! ! www.transcode.de @keimlink