Translating documentation using Sphinx¶
Sphinx is a tool for creating beautiful documentation. It uses simple reStructuredText syntax and can generate output in many formats. If you’re looking for an example, this documentation is also built using it. The very useful companion for using Sphinx is the Read the Docs service, which will build and publish your documentation for free.
I will not focus on writing documentation itself, if you need guidance with
that, just follow instructions on the Sphinx website. Once you have
documentation ready, translating it is quite easy as Sphinx comes with support
for this and it is quite nicely covered in their Internationalization. It’s
matter of few configuration directives and invoking of the sphinx-intl
tool.
If you are using Read the Docs service, you can start building translated documentation on the Read the Docs. Their Localization of Documentation covers pretty much everything you need - creating another project, set its language and link it from main project as a translation.
Now all you need is translating the documentation content. Sphinx generates PO
file for each directory or top level file, what can lead to quite a lot of
files to translate (depending on gettext_compact
settings).
You can import the index.po
into Weblate as an initial component and
then configure Descoberta de componentes addon to automatically
discover all others.
|
|
|
|
|
|
ficheiro gettext PO |
|
|
Expressão regular para corresponder ficheiros de tradução |
|
Personalizar nome do componente |
|
Defina o ficheiro base para as novas traduções |
|
Dica
Would you prefer Sphinx to generate just single PO file? There is a hacky
way to achieve this (used by Weblate documentation) by overriding Sphinx
way to get a Gettext domain of a document. Place following snippet to your
Sphinx configuration in conf.py
:
import sphinx.transforms.i18n
import sphinx.util.i18n
# Hacky way to have all localized content in single domain
sphinx.transforms.i18n.docname_to_domain = (
sphinx.util.i18n.docname_to_domain
) = lambda docname, compact: "docs"
This might be directly supported by Sphinx in future releases, see <https://github.com/sphinx-doc/sphinx/issues/784>.
Veja também
The Odorik python module documentation is built using Sphinx, Read the Docs and translated using Weblate.