Write The Docs EU — Markus Zapke-Gründemann — Writing multi-language documentation using Sphinx

Markus Zapke-Gründemann

I’m at Write The Docs EU today in Budapest and will post semi–unpolished notes from sessions throughout the day after each talk finishes.

Sphinx – Python Documentation Generator

Supports many output formats.

Internationalization (i18n): Translate into other languages without changing the code. GNU gettext is used frequently.

Tip: Install sphinx-intl to make it easier to setup.

Better to setup more automation. He found himself writing tools to show the workflow, rather than typing commands.

Transifex — Online translation service, and you can use “pip” to install transifex-client.

Tips for translating Sphinx documentation

  • Use English for all text inside code. The source code isn’t part of the translation.
  • Always use inline syntax, otherwise the URL will get lost when using aliases.
  • Maintain versioned URLs. Use extlinks extension to define URLs in the configuration.
  • Special cases — ifconfig
  • Link checking — linkcheck

What’s missing?

  • Build all languages at once.
  • Method to add a “landing page”.
  • Setting for translations.
  • Use gettext_compact to create a single catalog.
  • Language switch template.

Sphinx 1.3

  • Merge sphinx-into into Sphinx.
  • Move Transifex support from spinxh-intl to a new extension.
  • Allow to build all languages with a single command.

Published by

Bryan Villarin

Bryan works at Automattic. Cat whisperer. Sometimes, a photographer and card magician.

Talk to me, Goose

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s