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 Software Developer since 2001 Python, Django, Open Data and Training Owner of transcode Board member of the German Django Association keimlink.de // @keimlink
gettext Example import gettext t = gettext.translation('example', 'locale', fallback=True) _ = t.gettext print(_('Always look on the bright side of life'))
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
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 %} {{ owner.username }}'s bookmarks
How to handle URLs Always use the inline syntax: ! Alternatively, you can get the `Python Sources 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/
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 models/querysets/#queryset-api>`. ! Download the :djangopdf:`Django Offline PDF Documentation <>` which has currently more than 1,200 pages.
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