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 ...
Basics
Sphinx
Python Documentation Generator
Markup Language: reStructuredText
Output Formats: HTML, LaTeX (PDF), ePub, Texinfo, ...
Internationalization
Often referred to as i18n
Translating into other languages without changing the code
GNU gettext is u...
gettext Example
import gettext	
t = gettext.translation('example', 'locale', fallback=True)	
_ = t.ugettext	
print _('Writ...
Sphinx
Internationalization
Sphinx i18n
Workflow
Source: http://sphinx-doc.org/intl.html
Sphinx i18n
Configuration
docs/conf.py	
language = 'en'	
locale_dirs = ['locale/']	
# New in version 1.1	
gettext_compact =...
Sphinx i18n
Process
$ make gettext	
$ msginit --no-translator -l de_DE 	
-i _build/locale/setup.pot 	
-o locale/de/LC_MESS...
😧
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	
$...
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 <pr...
Handy tips
for translating
Sphinx documentation
Using code inside
the documentation
All text inside the code should be English:
!
class Bookmark(models.Model):	
url = mod...
How to handle URLs
Always use the inline syntax:
!
Alternatively, you can get the `Python Sources <http://python.org/
down...
How to maintain
versoined URLs
You can use the extlinks extension to define URLs in the configuration:
!
extlinks = {	
'djan...
How to handle
special cases
ifconfig can be used to handle special cases:	

!
.. ifconfig:: language == 'de'	
!
Nützliche ...
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 setti...
Sphinx 1.3
Merge sphinx-intl into Sphinx
Move Transifex support from sphinx-intl to a new extension
Allow to build all lan...
Thanks!
!
www.transcode.de
@keimlink
Upcoming SlideShare
Loading in …5
×

Writing multi-language documentation using Sphinx

3,668 views
3,318 views

Published on

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. I will talk about how Sphinx internationalization support works, which tools and services I use and how to organize the translation workflow. Finally I will have a look at what the future of internationalization in Sphinx might bring.

Published in: Engineering, Technology, Education
2 Comments
2 Likes
Statistics
Notes
No Downloads
Views
Total views
3,668
On SlideShare
0
From Embeds
0
Number of Embeds
15
Actions
Shares
0
Downloads
18
Comments
2
Likes
2
Embeds 0
No embeds

No notes for slide

Writing multi-language documentation using Sphinx

  1. 1. Writing multi-language Documentation using Sphinx Markus Zapke-Gründemann Write The Docs Europe 2014
  2. 2. Markus Zapke-Gründemann Software Developer since 2001 Python, Django, Open Data and Training Independent since 2008 Owner of transcode keimlink.de // @keimlink
  3. 3. Basics
  4. 4. Sphinx Python Documentation Generator Markup Language: reStructuredText Output Formats: HTML, LaTeX (PDF), ePub, Texinfo, manual pages, plain text sphinx-doc.org
  5. 5. Internationalization Often referred to as i18n Translating into other languages without changing the code GNU gettext is used frequently
  6. 6. gettext Example import gettext t = gettext.translation('example', 'locale', fallback=True) _ = t.ugettext print _('Write the Docs')
  7. 7. Sphinx Internationalization
  8. 8. Sphinx i18n Workflow Source: http://sphinx-doc.org/intl.html
  9. 9. Sphinx i18n Configuration docs/conf.py language = 'en' locale_dirs = ['locale/'] # New in version 1.1 gettext_compact = True
  10. 10. 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
  11. 11. 😧
  12. 12. sphinx-intl $ pip install sphinx-intl https://pypi.python.org/pypi/sphinx-intl
  13. 13. sphinx-intl $ make gettext $ sphinx-intl update -l de -p _build/locale # Translate documentation $ sphinx-intl build $ make SPHINXOPTS="-Dlanguage=de" html
  14. 14. Transifex
  15. 15. www.transifex.com
  16. 16. Transifex Setup $ pip install transifex-client $ tx init --user=<tx-username> --pass=<tx-password>
  17. 17. 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
  18. 18. Handy tips for translating Sphinx documentation
  19. 19. 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)
  20. 20. 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/
  21. 21. 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.
  22. 22. 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/>`_
  23. 23. Link checking You can check the links for each language separately: ! $ make SPHINXOPTS="-Dlanguage=de" linkcheck
  24. 24. 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
  25. 25. 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
  26. 26. Thanks! ! www.transcode.de @keimlink

×