sphinx / doc / translationguide.rst

Sphinx Document Translation Guide


This document describes the translation cycle of Sphinx-based document. For illustrative purpose, we use Sphinx document itself in this document.

The Sphinx document is included in the Sphinx code. It is managed by Mercurial and is hosted on BitBucket.

hg clone

Translate the document

Getting Started

These are the basic steps needed to start translating the Sphinx document.

  1. Clone the sphinx repository to your machine.

    hg clone
    cd sphinx/doc
  2. Add below settings to sphinx document's if not exists.

    locale_dirs = ['locale/']   #for example
    gettext_compact = False     #optional

    This case-study assumes that :confval:`locale_dirs` is set to 'locale/' and :confval:`gettext_compact` is set to False (the Sphinx document is already configured as such).

  3. Generate pot files from the document.

    make gettext

    As a result, many pot files are generated under _build/locale directory. By the way, :confval:`locale_dirs` is set to locale/ then locale/pot directory is proper location for pot files.

    mkdir locale
    cp -R _build/locale locale/pot
  4. Generate po files from pot files.

    Sphinx expects that translated po files are under locale/<lang>/LC_MESSAGES/ directory. For Japanese, you need locale/ja/LC_MESSAGE/ directory and po files under the directory. The po files can be copied and renamed from pot files:

    mkdir -p locale/ja/LC_MESSAGES
    cp -R locale/pot/* ja/LC_MESSAGES
    cd locale/ja/LC_MESSAGES
    find . -name "*.pot" -type f -print0 |while read -r -d '' file; do
    mv "$file" "${file%.*}.po";
  5. Translating!

    Translate po file under sphinx/doc/locale/ja/LC_MESSAGES directory. The case of builders.po:

    # a5600c3d2e3d48fc8c261ea0284db79b
    #: ../../builders.rst:4
    msgid "Available builders"

    Another case, msgid is multi-line text and contains reStructuredText syntax:

    # 302558364e1d41c69b3277277e34b184
    #: ../../builders.rst:9
    msgid ""
    "These are the built-in Sphinx builders. More builders can be added by "
    ":ref:`extensions <extensions>`."
    msgstr ""

    Please be careful not to break reST notation.

  6. Compile po files into mo.

    You need msgfmt command line tool to compile po files. For example, the case of debian, you can install the command by this command:

    sudo apt-get install gettext

    and do compile each po files:

    cd sphinx/doc/locale/ja/LC_MESSAGES
    msgfmt builders.po -o

    in one line:

    find . -name "*.po" -type f -print0 | while read -r -d '' file; do \
    msgfmt "$file" -o "${file%.*}.mo"; \
  7. Make translated html (or other format).

    Now you are ready to make the translated document by the :command:`make html` command. You need :confval:`language` parameter in or you may also specify the parameter on the command line.

    $ cd sphinx/doc
    $ make -e SPHINXOPTS="-D language='ja'" html

    Congratulations!! You got the translated document in _build/html directory.

Update your po files by new pot files

If the document is updated, it is necessary to generate updated pot files and to apply differences to translated po files. In order to apply the updating difference of a pot file to po file, using msgmerge command.

$ msgmerge -U locale/pot/builders.pot locale/ja/LC_MESSAGES/builders.po
........... done.

Using Transifex service for team translation

Make new translation project

  1. Create your transifex account (if not have) and login.

    For example:

    Transifex UserName:
    Transifex Password:
  2. Create new project for your document.

    Currently, transifex does not allow for a translation project to have more than one version of document, so you'd better include a version number in your project name.

    For example:

    Project ID:sphinx-document-test_1_0
    Project URL:

Install transifex client: tx

You need tx command to upload resources (pot files).

$ pip install transifex-client

Create config files for tx command

$ tx init --user=<transifex-username> --pass=<transifex-password>
Creating .tx folder...
Transifex instance []:
Creating skeleton...
Creating config file...
No authentication data found.
No entry found for host Creating...
Updating /home/ubuntu/.transifexrc file...

This process will create .tx/config in the current directory, as well as ~/.transifexrc file that includes auth information.

Register pot files in transifex

$ cd $BASEDIR/sphinx/doc
$ tx push -s
Pushing translations for resource
Pushing source file (locale/pot/builders.pot)
Resource does not exist.  Creating...


there is tx command wrapper tool to easier.

Forward the translation on transifex

Pull translated po files and make translated html

Get translated catalogs and build mo files (ex. for 'ja'):

$ cd $BASEDIR/sphinx/doc
$ tx pull -l ja
Pulling translations for resource (source: locale/pot/builders.pot)
 -> ja: locale/ja/LC_MESSAGES/builders.po

convert po files into mo:

$ msgfmt ....

Build html (ex. for 'ja'):

$ make -e SPHINXOPTS="-D language='ja'" html


Tranlating Tips

  • Translating local vs Transifex

    If you want to push all language's po files, you can use tx push -t. (this operation overwrites translations in transifex.)

  • rebuild

    :command:`make clean && make html`

Contributing to Sphinx reference translation

The recommended way for new contributors to translate Sphinx reference is to join the translation team on Transifex.

There is sphinx translation page for Sphinx-1.2 document.

  1. login to transifex service.
  2. go to sphinx translation page.
  3. push Request language and fill form.
  4. wait acceptance by transifex sphinx translation maintainers.
  5. (after acceptance) translate on transifex.