Knowledge Base

Documentation to help you use the POEditor localization platform effectively

How to translate Sphinx documentation

Owner Admin

After you collect the strings in your Sphinx documentation and generate a .pot file which includes all the translatable messages, you can use the translation platform POEditor to localize these messages.

How to generate the source file

Sphinx extracts the translatable strings using sphinx-build -b gettext. Each element in the doctree will result in a single string. A collection of .pot files will be available in your output directory after running MessageCatalogBuilder in Sphinx.

These gettext .pot files are supported by the translation platform POEditor and can be used to set up a translation project.

How to set up a translation project

If you don't have a POEditor account, you can create one here. Note you can manage the translation of up to 1000 strings for free with POEditor.

Once you're logged in to your POEditor account, you can create a project and add the source and target languages to it.

Then import the source .pot file(s) from Sphinx to the POEditor project using the Import functionality in the project page. If you have multiple .pot files, you can keep them grouped in the project by tagging each of them on import. This will also allow you to export each group of strings separately.

The imported source messages will be added as terms to the translation project.

Import terms and translations (Project page) - POEditor localization management platform

How to translate the Sphinx strings

To translate the strings from your Sphinx documentation imported from your gettext .pot file, you have multiple translation options. You can:

  • Assign your own contributors to translate specific languages
  • Crowdsource translations from your community with public projects
  • Order translation services from an integrated language service provider
  • Use machine translation (Google, Microsoft, DeepL).

You can find more information about each translation options here.

How to export the localized languages

There are multiple export options to download your localized Sphinx documentation in .po format. Note that you shouldn't export to .pot, because this file format won't contain your translations, only the source strings (the terms).

The most basic way to download the .po files is to use the Export functionality in any language page.

If you want to automate the import/export process, you can use the POEditor API or one of the integrations with code hosting platforms.


Related articles