Writing multi-language Documentation using Sphinx

Markus Zapke-Gründemann Write The Docs Europe 2014

Markus Zapke-Gründemann

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 Exampleimport gettext

t = gettext.translation('example', 'locale', fallback=True)

_ = t.ugettext

print _('Write the Docs')

Sphinx Internationalization

Sphinx i18n Workflow

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

Sphinx i18n Configuration

docs/conf.pylanguage = 'en'locale_dirs = ['locale/']# New in version 1.1gettext_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 URLsAlways use the inline syntax: !

Alternatively, you can get the `Python Sources <http://python.org/download/>`_ from the website and compile ityourself.!

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 <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'! Nützliche Links für 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?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

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