i18n API

sphinx.locale.init(locale_dirs, language, catalog='sphinx', namespace='general')[source]

Look for message catalogs in locale_dirs and ensure that there is at least a NullTranslations catalog set in translators. If called multiple times or if several .mo files are found, their contents are merged together (thus making init reentrable).

sphinx.locale.init_console(locale_dir, catalog)[source]

Initialize locale for console.

New in version 1.8.

sphinx.locale.get_translation(catalog, namespace='general')[source]

Get a translation function based on the catalog and namespace.

The extension can use this API to translate the messages on the extension:

import os
from sphinx.locale import get_translation

_ = get_translation(__name__)
text = _('Hello Sphinx!')

def setup(app):
    package_dir = path.abspath(path.dirname(__file__))
    locale_dir = os.path.join(package_dir, 'locales')
    app.add_message_catalog(__name__, locale_dir)

With this code, sphinx searches a message catalog from ${package_dir}/locales/${language}/LC_MESSAGES/${__name__}.mo The language is used for the searching.

New in version 1.8.

sphinx.locale._(message, *args)

Translation function for messages on documentation (menu, labels, themes and so on). This function follows language setting.

sphinx.locale.__(message, *args)

Translation function for console messages This function follows locale setting (LC_ALL, LC_MESSAGES and so on).