Sphinx i18n

Sphinx hat schon rudimentäre Unterstützung für die Internationalisierung von Dokumentationen mit Hilfe von gettext. Dieser Vortrag berichtet über die eigenen Erfahrungen und diskutiert weitergehende Lösungsansätze.

Transcript

1. Sphinx i18n Markus Zapke-Gründemann PyCon DE 2013
2. Markus Zapke-Gründemann Softwareentwickler seit 2001 Softwareentwicklung mit Python, Django und Mercurial Selbstständig seit 2008 Inhaber von transcode keimlink.de // @keimlink
3. Sphinx Python Documentation Generator Auszeichnungssprache: reStructuredText Ausgabeformate: HTML, LaTeX (PDF), Texinfo, manual pages, plain text sphinx-doc.org
4. i18n i18n == internationalization Anpassung an andere Sprachen ohne den Code zu ändern Häufig wird GNU gettext genutzt
5. Eine Dokumentation für alle Sprachen oder eine Dokumentation für jede Sprache?
6. Sphinx i18n Quelle: http://sphinx-doc.org/intl.html
7. Sphinx i18n Konfiguration docs/conf.py language = 'en' locale_dirs = ['locale/'] # New in version 1.1 gettext_compact = True
8. Sphinx i18n Prozess $ make gettext $ msginit --no-translator -l de_DE \ -i _build/locale/setup.pot \ -o locale/de/LC_MESSAGES/setup.po # Texte übersetzen $ msgfmt --check-format \ -D locale/de/LC_MESSAGES setup.po \ -o locale/de/LC_MESSAGES/setup.mo $ make SPHINXOPTS="-Dlanguage=de" html
9. ☹
10. Sphinx i18n Prozess ab 1.2 $ pip install sphinx-intl $ make gettext $ sphinx-intl update -l de \ -p _build/locale # Texte übersetzen $ sphinx-intl build $ make SPHINXOPTS="-Dlanguage=de" html https://pypi.python.org/pypi/sphinx-intl
11. Tipps zur Arbeit mit Sphinx i18n
12. Code in der Dokumentation Der Code sollte alle Zeichenketten in Englisch enthalten: class Bookmark(models.Model): url = models.URLField() title = models.CharField('title', max_length=255) description = models.TextField('description', blank=True)
13. Umgang mit URLs URLs müssen immer inline notiert werden: Alternatively, you can get the `Python Sources <http:// python.org/download/>`_ from the website and compile it yourself. Denn so geht der URL bei der Übersetzung verloren: Alternatively, you can get the `Python Sources`_ from the website and compile it yourself. .. _Python Sources: http://python.org/download/
14. Umgang mit URLs Mit extlinks kann man auch dynamische URLs übersetzen: extlinks = { 'djangodocs': ('https://docs.djangoproject.com/en/1.5/%s', None) } Download the :djangopdf:`Django Offline PDF Documentation <>` which has currently more than 1,200 pages.
15. Umgang mit Sonderfällen Mit ifconfig ist es möglich Sonderfälle zu behandeln: .. ifconfig:: language == 'de' Nützliche Links für deutschsprachige Django-Nutzer: - `Deutschsprachige Django-Community <http://django-de.org/>`_
16. Probleme mit Sphinx i18n Die index Directive wird nicht übersetzt Eigene Templates werden nicht übersetzt linkcheck nur für RST-Dateien Eigene Lösung mit linkchecker möglich WARNING: Literal block expected; none found.
17. Was fehlt noch? Es gibt noch kein Werkzeug, um die Dokumentation für alle Sprachen auf einmal zu erzeugen. Evtl. ist eine „Landing Page“ nötig. Sphinx sollte in der Navigation einen Umschalter für die Sprachen anbieten.
18. Danke! www.transcode.de @keimlink