Skip to main content

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

Project description

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 conf.py:

    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

Installation

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

Commands

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:

export SPHINXINTL_LANGUAGE=de,ja

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

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

Setup sphinx conf.py

Add below settings to sphinx document’s conf.py 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.

License

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

Original

This utilty derived from these projects.

CHANGES

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 conf.py 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 conf.py’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 conf.py 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 conf.py.

  • 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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinx-intl-0.9.6.tar.gz (13.7 kB view hashes)

Uploaded Source

Built Distribution

sphinx_intl-0.9.6-py2.py3-none-any.whl (14.6 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page