Sphinx, the Python Documentation Generator, provides Internationalization . The workflow is described there.

btw: documentation reference can be build with intersphinx Check available options:

python -m sphinx.ext.intersphinx 'http://www.sphinx-doc.org/en/master/objects.inv'


Install requirements:

pip install -r requirements.txt


To initial a new documentation project use:


Zanata Project File

To interact to Zanata server with the client a project configuration file named zanata.xml is required:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<config xmlns="http://zanata.org/namespace/config/">
    <rule pattern="**/*.pot">{path}/{locale_with_underscore}/LC_MESSAGES/{filename}.po</rule>

url must match with url name in zanata.ini


Build gettext files for Zanata:

sphinx-build -b gettext doc/myguide/source/ doc/myguide/source/locale/

Push to server

Push pot files to Zanata:

zanata-cli -e push --disable-ssl-cert

Normaly self-signed certificate will used in private environment like this. The option –disable-ssl-cert will force the client to connect.

Now the translation files are on the server and translatable in the configured languages. If this done you can download it again.

Pull from server

Pull po files from Zanata:

zanata-cli -e pull -l de  --disable-ssl-cert

Use language option -l de for German files, without that all language files will be download.

Optional: If you modified the language files locally, you can push them to the server:

zanata-cli -e push --push-type trans --disable-ssl-cert

Build and publish

At the end, build and publish the docs:

sphinx-build -b html doc/myguide/source/ doc/myguide/build/html/en
sphinx-build -b html doc/myguide/source/ doc/myguide/build/html/de -D language='de'

Or build and publish slides within hieroglyph module:

sphinx-build -b slides doc/myguide/source/ doc/myguide/build/slides/en
sphinx-build -b slides doc/myguide/source/ doc/myguide/build/slides/de -D language='de'