skip to navigation
skip to content

sphinx-intl 0.9.7

Sphinx utility that make it easy to translate and to apply translation.

sphinx-intl is a utility tool that provides several features that make it easy to translate and to apply translation to Sphinx generated document. Optional: support the Transifex service for translation with Sphinx .

QuickStart for sphinx translation

This section describe to translate with Sphinx and sphinx-intl command.

  1. Create your document by using Sphinx.

  2. Add configurations to your

    locale_dirs = ['locale/']   #path is example but recommended.
    gettext_compact = False     #optional.

    locale_dirs is required and gettext_compact is optional.

  3. Extract document’s translatable messages into pot files:

    $ make gettext
  4. Setup/Update your locale_dir:

    $ sphinx-intl update -p _build/locale -l de -l ja

    Done. You got these directories that contain po files:

    • ./locale/de/LC_MESSAGES/
    • ./locale/ja/LC_MESSAGES/
  5. Translate your po files under ./locale/<lang>/LC_MESSAGES/.

  6. Build mo files and make translated document:

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

That’s all!

Basic Features

  • create or update po files from pot files.
  • build mo files from po files.

Requirements for basic

Optional features

These features need transifex-client library.

  • create .transifexrc file from environment variable, without interactive input.
  • create .tx/config file without interactive input.
  • update .tx/config file from locale/pot files automatically.
  • build mo files from po files in the locale directory.

You need to use tx command for below features:

  • tx push -s : push pot (translation catalogs) to transifex.
  • tx pull -l ja : pull po (translated catalogs) from transifex.

Requirements for optional

  • Python 2.5, 2.6, 2.7. (transifex-client only support 2.x)
  • Your transifex account if you want to download po files from transifex or you want to translate on transifex.
  • external library: transifex-client


Recommend strongly: use virtualenv for this procedure:

$ pip install sphinx-intl

If you want to use Optional Features, you need install additional library:

$ pip install sphinx-intl[transifex]

Commands, options, environment variables


Type sphinx-intl without arguments, options to show command help.

Setup environment variables

All command-line options can be set with environment variables using the format SPHINXINTL_<UPPER_LONG_NAME> . Dashes (-) have to replaced with underscores (_).

For example, to set the languages:


This is the same as passing the option to sphinx-intl directly:

sphinx-intl <command> --language=de --language=ja

Setup sphinx

Add below settings to sphinx document’s if not exists:

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

Setup Makefile / make.bat

make gettext will generate pot files into _build/locale directory, however pot files should be generated in the locale/pot is convenient. You can be done by replacing _build/locale with locale/pot in your Makefile and/or make.bat that was generated by sphinx-quickstart.


Licensed under the BSD license. See the LICENSE file for specific terms.


0.9.7 (2015/11/07)

  • Drop supporting Python-3.1 and 3.2
  • Depends to click for command-line feature.

0.9.6 (2015/09/22)

  • PR#6: Fix update_txconfig_resources command raise errors with pot filename including symbols and spaces. Thanks to Takeshi Komiya.
  • PR#7: Fix sphinx-intl could not find in projects separating build and source directories. Thanks to Takeshi Komiya.
  • PR#8: Detects pot_dir automatically if sphinx has generated. Thanks to Takeshi Komiya.
  • PR#9: Support fuzzy translations. Thanks to Guilherme Brondani Torri.
  • PR#10: Add __file__ to’s namespace.
  • On Windows environment, now using “transifex<0.9” because “transifex>=0.9” requires unnecessary py2exe installation.

0.9.5 (2014/07/10)

  • Fix: PR#2, PR#4: update-txconfig-resources disregarded –pot-dir option. Thanks to Giacomo Spettoli, Takeshi Komiya.
  • Fix: PR#5: update-txconfig-resources command raise errors when project name includes spaces and dots. Thanks to Takeshi Komiya.
  • PR#3: Skip building process if mo file is newer than po file. Thanks to Nozomu Kaneko.
  • Add supporting Python-3.4

0.9.4 (2013/12/10)

  • Fix: sphinx-intl didn’t use SPHINXINTL_CONFIG environment value.
  • Feature #3: update-txconfig-resources command now detect project-name from .tx/config that already exists.
  • Now using setuptools instead of distribute.
  • Fix: tox test raises a error with transifex-client-0.10

0.9.3 (2013/04/20)

  • Fix: because –config option did not consider directory path, locale_dir did not contain directory path to file.

0.9.2 (2013/4/11)

  • Add stat command for displaying statistics like ‘msgfmt –statistics’.
  • Documentation and error messages are improved.
  • Fix: update command did not detect pot/po difference when translated count and untranslated count are not difference.

0.9.1 (2013/4/10)

  • Add flake8 test and fix some errors.
  • Add –pot-dir option. default is pot directory under locale_dir. If you using Sphinx default settings, -p _build/locale is useful.
  • Add append/deprecated msgid count information for update command.
  • Drop multiple locale directories feature. Now use only first directory of locale_dirs in
  • Fix: -c option is not working. Thanks @tk0miya!

0.9.0 (2013/4/7)

  • First release that provides these commands:
    • update
    • build
    • create-transifexrc
    • create-txconfig
    • update-txconfig-resources
File Type Py Version Uploaded on Size
sphinx-intl-0.9.7.tar.gz (md5) Source 2015-11-07 12KB
sphinx_intl-0.9.7-py2.py3-none-any.whl (md5) Python Wheel 3.4 2015-11-07 13KB
  • Downloads (All Versions):
  • 152 downloads in the last day
  • 591 downloads in the last week
  • 2894 downloads in the last month