This document discusses using Sphinx to generate documentation in multiple languages. It introduces Sphinx and the Sphinx-intl extension for internationalization. The workflow involves configuring Sphinx with locale directories and languages, generating POT files with sphinx-intl, translating strings externally with Transifex or by building PO files, and building the documentation for different languages by setting the language variable. It provides tips for translating like handling code snippets, URLs, and special cases using directives like ifconfig.

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> --pass=<tx-password>

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