Categories
Tech

Translate Text in Sphinx Templates and Configurations

Weeks ago when I was playing around with the docs of EFB and the Crowdin translation widget, I realized that the default theme for Sphinx — Alabaster isn’t really doing well in term of translation. It seems like the author isn’t really confident on that (or simply didn’t care since 4 years ago).

As the theme itself is open source, and Sphinx is flexible enough, couldn’t we just translate it ourselves? It turns out that things are not that complicated.

Categories
Tech

Translate README files in reStructuredText with Sphinx

reStructuredText (reST) is a markup language that is popular in the Python developers community. reST is the standard markup language for docutils, Sphinx documentation generator, and the Python Package Index (PyPI). However, reST by now is still not popular enough. Most translation platforms, including Crowdin which I’m using now for EH Forwarder Bot, have no support to reST documents.

Sphinx has provided a plug-in sphinx-intl, which extract strings from reST documents and compile into GNU gettext message catalog template (.pot) files, and build new documents with translated strings in other languages. GNU gettext formats are widely accepted by translation platforms, making our life much easier. This would work out-of-box if you are generating HTML or PDF documentations, but not so simple if you want a reST output.