Writing multi-language documentation using Sphinx

Writing multi-language documentation using Sphinx

How to write multi-language documentation? What tools can you use? What mistakes should you avoid? This talk is based on the experiences I gathered while working on several multi-language documentation projects using Sphinx.


Markus Zapke-Gründemann

July 23, 2014


  1. Writing multi-language Documentation using Sphinx Markus Zapke-Gründemann EuroPython 2014

  2. Markus Zapke-Gründemann Software Developer since 2001 Python, Django, Open Data

    and Training Owner of transcode Board member of the German Django Association keimlink.de // @keimlink
  3. Basics

  4. Sphinx Python Documentation Generator Markup Language: reStructuredText Output Formats: HTML,

    LaTeX (PDF), ePub, Texinfo, manual pages, plain text sphinx-doc.org
  5. Internationalization Often referred to as i18n Translating into other languages

    without changing the code GNU gettext is used frequently
  6. gettext Example import gettext t = gettext.translation('example', 'locale', fallback=True) _

    = t.gettext print(_('Always look on the bright side of life'))
  7. Why use gettext for translated documentation? Untranslated strings are displayed

    in the source language Markup is not duplicated Professional translation tools can be used Contributions possible without using a VCS
  8. Sphinx Internationalization

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

  10. Sphinx i18n Configuration docs/conf.py language = 'en' locale_dirs = ['locale/']

    # New in version 1.1 gettext_compact = True
  11. sphinx-intl $ pip install sphinx-intl https://pypi.python.org/pypi/sphinx-intl

  12. sphinx-intl $ make gettext $ sphinx-intl update -l de -p

    _build/locale # Translate documentation $ sphinx-intl build $ make SPHINXOPTS="-Dlanguage=de" html
  13. Transifex

  14. www.transifex.com

  15. Transifex Setup $ pip install transifex-client $ tx init --user=<tx-username>

  16. Transifex and sphinx-intl $ sphinx-intl update-txconfig-resources \ --pot-dir _build/locale \

    --transifex-project-name <project_name> $ tx push -s # Translate documentation on Transifex $ tx pull -l de $ sphinx-intl build $ make SPHINXOPTS="-Dlanguage=de" html
  17. Handy tips for translating Sphinx documentation

  18. Using code inside the documentation All text inside the code

    should be English: ! {% extends "marcador/bookmark_list.html" %} ! {% block title %}{{ owner.username }}'s bookmarks{% endblock %} ! {% block heading %} <h2>{{ owner.username }}'s bookmarks<br> <small>{{ bookmarks.count }} bookmarks in total</small> </h2> {% endblock %}
  19. How to handle URLs Always use the inline syntax: !

    Alternatively, you can get the `Python Sources <http://python.org/ download/>`_ 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/
  20. 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 <ref/ models/querysets/#queryset-api>`. ! Download the :djangopdf:`Django Offline PDF Documentation <>` which has currently more than 1,200 pages.
  21. 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 <http://django-de.org/>`_
  22. Link checking You can check the links for each language

    separately: ! $ make SPHINXOPTS="-Dlanguage=de" linkcheck
  23. What is still missing? A translations setting to build all

    languages with a single command A way to add a „landing page“ Use gettext_compact to create a single catalog Collect all indices into a single .po file A language switch template
  24. Thanks! ! www.transcode.de @keimlink