![Page 1: Writing multi-language documentation using Sphinx](https://reader031.vdocuments.us/reader031/viewer/2022013110/541597608d7f72316c8b4763/html5/thumbnails/1.jpg)
Writing multi-language Documentation using Sphinx
Markus Zapke-Gründemann EuroPython 2014
![Page 2: Writing multi-language documentation using Sphinx](https://reader031.vdocuments.us/reader031/viewer/2022013110/541597608d7f72316c8b4763/html5/thumbnails/2.jpg)
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
![Page 3: Writing multi-language documentation using Sphinx](https://reader031.vdocuments.us/reader031/viewer/2022013110/541597608d7f72316c8b4763/html5/thumbnails/3.jpg)
Basics
![Page 4: Writing multi-language documentation using Sphinx](https://reader031.vdocuments.us/reader031/viewer/2022013110/541597608d7f72316c8b4763/html5/thumbnails/4.jpg)
Sphinx
Python Documentation Generator
Markup Language: reStructuredText
Output Formats: HTML, LaTeX (PDF), ePub, Texinfo, manual pages, plain text
sphinx-doc.org
![Page 5: Writing multi-language documentation using Sphinx](https://reader031.vdocuments.us/reader031/viewer/2022013110/541597608d7f72316c8b4763/html5/thumbnails/5.jpg)
Internationalization
Often referred to as i18n
Translating into other languages without changing the code
GNU gettext is used frequently
![Page 6: Writing multi-language documentation using Sphinx](https://reader031.vdocuments.us/reader031/viewer/2022013110/541597608d7f72316c8b4763/html5/thumbnails/6.jpg)
gettext Exampleimport gettext
t = gettext.translation('example', 'locale', fallback=True)
_ = t.gettext
print(_('Always look on the bright side of life'))
![Page 7: Writing multi-language documentation using Sphinx](https://reader031.vdocuments.us/reader031/viewer/2022013110/541597608d7f72316c8b4763/html5/thumbnails/7.jpg)
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
![Page 8: Writing multi-language documentation using Sphinx](https://reader031.vdocuments.us/reader031/viewer/2022013110/541597608d7f72316c8b4763/html5/thumbnails/8.jpg)
Sphinx Internationalization
![Page 10: Writing multi-language documentation using Sphinx](https://reader031.vdocuments.us/reader031/viewer/2022013110/541597608d7f72316c8b4763/html5/thumbnails/10.jpg)
Sphinx i18n Configuration
docs/conf.pylanguage = 'en'locale_dirs = ['locale/']# New in version 1.1gettext_compact = True
![Page 11: Writing multi-language documentation using Sphinx](https://reader031.vdocuments.us/reader031/viewer/2022013110/541597608d7f72316c8b4763/html5/thumbnails/11.jpg)
sphinx-intl
$ pip install sphinx-intl
https://pypi.python.org/pypi/sphinx-intl
![Page 12: Writing multi-language documentation using Sphinx](https://reader031.vdocuments.us/reader031/viewer/2022013110/541597608d7f72316c8b4763/html5/thumbnails/12.jpg)
sphinx-intl
$ make gettext$ sphinx-intl update -l de -p _build/locale# Translate documentation$ sphinx-intl build$ make SPHINXOPTS="-Dlanguage=de" html
![Page 13: Writing multi-language documentation using Sphinx](https://reader031.vdocuments.us/reader031/viewer/2022013110/541597608d7f72316c8b4763/html5/thumbnails/13.jpg)
Transifex
![Page 15: Writing multi-language documentation using Sphinx](https://reader031.vdocuments.us/reader031/viewer/2022013110/541597608d7f72316c8b4763/html5/thumbnails/15.jpg)
Transifex Setup
$ pip install transifex-client$ tx init --user=<tx-username> --pass=<tx-password>
![Page 16: Writing multi-language documentation using Sphinx](https://reader031.vdocuments.us/reader031/viewer/2022013110/541597608d7f72316c8b4763/html5/thumbnails/16.jpg)
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
![Page 17: Writing multi-language documentation using Sphinx](https://reader031.vdocuments.us/reader031/viewer/2022013110/541597608d7f72316c8b4763/html5/thumbnails/17.jpg)
Handy tips for translating
Sphinx documentation
![Page 18: Writing multi-language documentation using Sphinx](https://reader031.vdocuments.us/reader031/viewer/2022013110/541597608d7f72316c8b4763/html5/thumbnails/18.jpg)
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 %}
![Page 19: Writing multi-language documentation using Sphinx](https://reader031.vdocuments.us/reader031/viewer/2022013110/541597608d7f72316c8b4763/html5/thumbnails/19.jpg)
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/
![Page 20: Writing multi-language documentation using Sphinx](https://reader031.vdocuments.us/reader031/viewer/2022013110/541597608d7f72316c8b4763/html5/thumbnails/20.jpg)
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.
![Page 21: Writing multi-language documentation using Sphinx](https://reader031.vdocuments.us/reader031/viewer/2022013110/541597608d7f72316c8b4763/html5/thumbnails/21.jpg)
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/>`_
![Page 22: Writing multi-language documentation using Sphinx](https://reader031.vdocuments.us/reader031/viewer/2022013110/541597608d7f72316c8b4763/html5/thumbnails/22.jpg)
Link checking
You can check the links for each language separately: !
$ make SPHINXOPTS="-Dlanguage=de" linkcheck
![Page 23: Writing multi-language documentation using Sphinx](https://reader031.vdocuments.us/reader031/viewer/2022013110/541597608d7f72316c8b4763/html5/thumbnails/23.jpg)
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