Sphinx i18n

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.

16ae0a49ce39c086a67090ad54fbf67f?s=128

Markus Zapke-Gründemann

October 15, 2013
Tweet

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. 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
  10. Tipps zur Arbeit mit Sphinx i18n

  11. 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)
  12. 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/
  13. 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.
  14. 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/>`_
  15. 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.
  16. 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.
  17. Danke! www.transcode.de @keimlink