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. I will talk about how Sphinx internationalization support works, which tools and services I use and how to organize the translation workflow. Finally I will have a look at what the future of internationalization in Sphinx might bring.

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

2. Markus
Zapke-Gründemann
Software Developer since 2001
Python, Django, Open Data and Training
Independent since 2008
Owner of transcode
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.ugettext
print _('Write the Docs')

7. Sphinx
Internationalization

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

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

10. 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

11. 😧

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

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

14. Transifex

15. www.transifex.com

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

17. 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

18. Handy tips
for translating
Sphinx documentation

19. 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)

20. 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/

21. 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.

22. 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/>`_

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

24. 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

25. 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

26. Thanks!
!
www.transcode.de
@keimlink