Writing multi-language documentation using Sphinx

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.

Transcript

1. Writing multi-language
   Documentation using Sphinx
   Markus Zapke-Gründemann
   EuroPython 2014
   

   View Slide

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

   View Slide

3. Basics
   

   View Slide

4. Sphinx
   Python Documentation Generator
   Markup Language: reStructuredText
   Output Formats: HTML, LaTeX (PDF), ePub, Texinfo, manual
   pages, plain text
   sphinx-doc.org
   

   View Slide

5. Internationalization
   Often referred to as i18n
   Translating into other languages without changing the code
   GNU gettext is used frequently
   

   View Slide

6. gettext Example
   import gettext
   t = gettext.translation('example', 'locale', fallback=True)
   _ = t.gettext
   print(_('Always look on the bright side of life'))
   

   View Slide

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

   View Slide

8. Sphinx
   Internationalization
   

   View Slide

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

   View Slide

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

    View Slide

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

    View Slide

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

    View Slide

13. Transifex
    

    View Slide

14. www.transifex.com
    

    View Slide

15. Transifex Setup
    $ pip install transifex-client
    $ tx init --user= --pass=
    

    View Slide

16. Transifex and sphinx-intl
    $ sphinx-intl update-txconfig-resources \
    --pot-dir _build/locale \
    --transifex-project-name
    $ tx push -s
    # Translate documentation on Transifex
    $ tx pull -l de
    $ sphinx-intl build
    $ make SPHINXOPTS="-Dlanguage=de" html
    

    View Slide

17. Handy tips
    for translating
    Sphinx documentation
    

    View Slide

18. 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 %}
    {{ owner.username }}'s bookmarks
    
    {{ bookmarks.count }} bookmarks in total
    
    {% endblock %}
    

    View Slide

19. How to handle URLs
    Always use the inline syntax:
    !
    Alternatively, you can get the `Python Sources 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/
    

    View Slide

20. 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 models/querysets/#queryset-api>`.
    !
    Download the :djangopdf:`Django Offline PDF Documentation <>` which has currently more
    than 1,200 pages.
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide