Writing multi-language Documentation using Sphinx

Markus Zapke-Grndemann Write The Docs Europe 2014

Markus Zapke-Grndemann
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 Workow

Source: http://sphinx-doc.org/intl.html

Sphinx i18n Conguration

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

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

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

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

How to maintain versoined URLs

You can use the extlinks extension to dene URLs in the conguration:
!

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.

How to handle special cases

ifconfig can be used to handle special cases:!
!

.. ifconfig:: language == 'de'!

!

Ntzliche Links fr deutschsprachige Django-Nutzer:!

!

- `Deutschsprachige Django-Community <http://django-de.org/>`_!

Link checking
You can check the links for each language separately:
!

$ make SPHINXOPTS="-Dlanguage=de" linkcheck

What is still missing?

Its 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