.. currentmodule:: sphinx.locale
.. autofunction:: init
.. autofunction:: init_console
.. autofunction:: get_translation
.. autofunction:: _
.. autofunction:: __
.. versionadded:: 1.8
An extension may naturally come with message translations. This is briefly summarized in :func:`sphinx.locale.get_translation` help.
In practice, you have to:
Choose a name for your message catalog, which must be unique. Usually the name of your extension is used for the name of message catalog.
Mark in your extension sources all messages as translatable, via :func:`sphinx.locale.get_translation` function, usually renamed
_()
, e.g.:from sphinx.locale import get_translation MESSAGE_CATALOG_NAME = 'myextension' _ = get_translation(MESSAGE_CATALOG_NAME) translated_text = _('Hello Sphinx!')
Set up your extension to be aware of its dedicated translations:
def setup(app): package_dir = path.abspath(path.dirname(__file__)) locale_dir = os.path.join(package_dir, 'locales') app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)
Generate message catalog template
*.pot
file, usually inlocale/
source directory, for example via Babel:$ pybabel extract --output=src/locale/myextension.pot src/
Create message catalogs (
*.po
) for each language which your extension will provide localization, for example via Babel:$ pybabel init --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale --locale=fr_FR
Translate message catalogs for each language manually
Compile message catalogs into
*.mo
files, for example via Babel:$ pybabel compile --directory=src/locale --domain=myextension
Ensure that message catalog files are distributed when your package will be installed, by adding equivalent line in your extension
MANIFEST.in
:recursive-include src *.pot *.po *.mo
When the messages on your extension has been changed, you need to also update message catalog template and message catalogs, for example via Babel:
$ pybabel extract --output=src/locale/myextension.pot src/
$ pybabel update --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale