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 is a Trust & Safety Wrangler at Automattic. He's also a photographer, card magician, and cat whisperer. (Thanks to my friend and colleague Steve Blythe for the sweet photo!)

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 )

Google photo

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

Twitter picture

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

Facebook photo

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

Connecting to %s