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

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.