API i18n

sphinx.locale.init(locale_dirs: List[Optional[str]], language: Optional[str], catalog: str = 'sphinx', namespace: str = 'general')Tuple[gettext.NullTranslations, bool][código fonte]

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 reentrant).

sphinx.locale.init_console(locale_dir: str, catalog: str)Tuple[gettext.NullTranslations, bool][código fonte]

Inicialize o código do idioma para o console.

Novo na versão 1.8.

sphinx.locale.get_translation(catalog: str, namespace: str = 'general')Callable[código fonte]

Obtenha uma função de tradução baseada no catálogo e no namespace.

A extensão pode usar essa API para traduzir as mensagens na extensão:

import os
from sphinx.locale import get_translation

MESSAGE_CATALOG_NAME = 'myextension'  # name of *.pot, *.po and *.mo files
_ = get_translation(MESSAGE_CATALOG_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(MESSAGE_CATALOG_NAME, locale_dir)

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

Novo na versão 1.8.

sphinx.locale._(message: str, *args: Any)str

Função de tradução para mensagens na documentação (menu, etiquetas, temas e assim por diante). Esta função segue a configuração language.

sphinx.locale.__(message: str, *args: Any)str

Função de tradução para mensagens do console. Essa função segue a configuração de localidade (LC_ALL, LC_MESSAGES e assim por diante).

Extension internationalization (i18n) and localization (l10n) using i18n API

Novo na versão 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:

  1. 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.

  2. Mark in your extension sources all messages as translatable, via sphinx.locale.get_translation() function, usually renamed _(), e.g.:

    src/__init__.py
    from sphinx.locale import get_translation
    
    MESSAGE_CATALOG_NAME = 'myextension'
    _ = get_translation(MESSAGE_CATALOG_NAME)
    
    translated_text = _('Hello Sphinx!')
    
  3. Set up your extension to be aware of its dedicated translations:

    src/__init__.py
    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)
    
  4. Generate message catalog template *.pot file, usually in locale/ source directory, for example via Babel:

    $ pybabel extract --output=src/locale/myextension.pot src/
    
  5. 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
    
  6. Translate message catalogs for each language manually

  7. Compile message catalogs into *.mo files, for example via Babel:

    $ pybabel compile --directory=src/locale --domain=myextension
    
  8. Ensure that message catalog files are distributed when your package will be installed, by adding equivalent line in your extension MANIFEST.in:

    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