i18n API¶
-
sphinx.locale.
init
(locale_dirs, language, catalog='sphinx', namespace='general')[源代码]¶ 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 makinginit
reentrant).
-
sphinx.locale.
get_translation
(catalog, namespace='general')[源代码]¶ 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
Thelanguage
is used for the searching.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).
Extension internationalization (i18n) and localization (l10n) using i18n API¶
1.8 新版功能.
An extension may naturally come with message translations. This is briefly
summarized in 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
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