Writing multi-language documentation using Sphinx

Writing multi-language Documentation using Sphinx

Markus Zapke-Gründemann EuroPython 2014

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

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

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-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: !

{% 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 %}

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

Thanks! !

www.transcode.de @keimlink