Diese Präsentation wurde erfolgreich gemeldet.
Wir verwenden Ihre LinkedIn Profilangaben und Informationen zu Ihren Aktivitäten, um Anzeigen zu personalisieren und Ihnen relevantere Inhalte anzuzeigen. Sie können Ihre Anzeigeneinstellungen jederzeit ändern.
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
Nächste SlideShare
Wird geladen in …5
×
Nächste SlideShare
Sphinx + robot framework = documentation as result of functional testing
Weiter
Herunterladen, um offline zu lesen und im Vollbildmodus anzuzeigen.

5

Teilen

Herunterladen, um offline zu lesen

Writing multi-language documentation using Sphinx

Herunterladen, um offline zu lesen

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.

Ähnliche Bücher

Kostenlos mit einer 30-tägigen Testversion von Scribd

Alle anzeigen

Ähnliche Hörbücher

Kostenlos mit einer 30-tägigen Testversion von Scribd

Alle anzeigen

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
  • KristofferAndersson12

    Oct. 3, 2019
  • AdrienANDRE

    Jun. 28, 2019
  • Edidiongasikpo

    Jun. 15, 2019
  • lcaballero

    Oct. 19, 2014
  • lucypark

    Aug. 16, 2014

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.

Aufrufe

Aufrufe insgesamt

7.937

Auf Slideshare

0

Aus Einbettungen

0

Anzahl der Einbettungen

21

Befehle

Downloads

40

Geteilt

0

Kommentare

0

Likes

5

×