sphinx-intl: translation support utility for Sphinx
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
- Basic Features
- Optional features
- Commands, options, environment variables
This section describe to translate with Sphinx and sphinx-intl command.
Create your document by using Sphinx.
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.
Extract document's translatable messages into pot files:
$ make gettext
Setup/Update your locale_dir:
$ sphinx-intl update -p _build/locale -l de -l ja
Done. You got these directories that contain po files:
Translate your po files under ./locale/<lang>/LC_MESSAGES/.
Build mo files and make translated document:
$ sphinx-intl build $ make -e SPHINXOPTS="-D language='ja'" html
- create or update po files from pot files.
- build mo files from po files.
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.
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]
Type sphinx-intl without arguments, options to show command help.
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 --language=de --language=ja <command>
Add below settings to sphinx document's conf.py if not exists:
locale_dirs = ['locale/'] #for example gettext_compact = False #optional
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.
This utilty derived from these projects.
#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.
- 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.
#3: Skip building process if mo file is newer than po file. Thanks to Nozomu Kaneko.
- Add supporting Python-3.4
- Fix: sphinx-intl didn't use SPHINXINTL_CONFIG environment value.
#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
- Fix: because --config option did not consider directory path, locale_dir did not contain directory path to conf.py file.
- 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.
- 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 Takeshi Komiya!
- First release that provides these commands: