API i18n

sphinx.locale.init(locale_dirs: Iterable[str | os.PathLike[str] | None], language: str | None, catalog: str = 'sphinx', namespace: str = 'general') → tuple[NullTranslations, bool][código-fonte]

Procure catálogos de mensagens em locale_dirs e certifique-se de que haja pelo menos um catálogo NullTranslations definido em translators. Se chamado várias vezes ou se vários arquivos .mo forem encontrados, seus conteúdos são mesclados (tornando o init reentrante).

sphinx.locale.init_console(locale_dir: str | os.PathLike[str] | None = None, catalog: str = 'sphinx') → tuple[NullTranslations, bool][código-fonte]

Inicialize o código do localidade para o console.

Adicionado na versão 1.8.

sphinx.locale.get_translation(catalog: str, namespace: str = 'general') → Callable[[str], str][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:

from pathlib import Path
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(__file__).resolve().parent
    locale_dir = package_dir / 'locales'
    app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)

Com este código, o sphinx pesquisa um catálogo de mensagens em ${package_dir}/locales/${language}/LC_MESSAGES/myextension.mo. O language é usado para a pesquisa.

Adicionado na versão 1.8.

sphinx.locale._(message: str) → 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) → 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).

Internacionalização de extensão (i18n) e localização (l10n) usando API i18n

Adicionado na versão 1.8.

Uma extensão pode vir naturalmente com traduções de mensagens. Isso é resumido brevemente na ajuda sphinx.locale.get_translation().

Na prática, você tem que:

  1. Escolha um nome para o seu catálogo de mensagens, que deve ser exclusivo. Normalmente, o nome do seu ramal é usado para o nome do catálogo de mensagens.

  2. Marque em suas fontes de extensão todas as mensagens como traduzíveis, através da função sphinx.locale.get_translation(), geralmente renomeada para _(), por exemplo:

    src/__init__.py
    from sphinx.locale import get_translation

MESSAGE_CATALOG_NAME = 'myextension'
_ = get_translation(MESSAGE_CATALOG_NAME)

translated_text = _('Hello Sphinx!')

  3. Configure sua extensão para estar ciente de suas traduções dedicadas:

    src/__init__.py
    def setup(app):
    package_dir = Path(__file__).resolve().parent
    locale_dir = package_dir / 'locales'
    app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)

  4. Gere o arquivo modelo de catálogo de mensagens *.pot, geralmente no diretório fonte locale/, por exemplo via Babel:

    $ pybabel extract --output=src/locale/myextension.pot src/

  5. Crie catálogos de mensagens (*.po) para cada idioma para o qual sua extensão fornecerá localização, por exemplo via Babel:

    $ pybabel init --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale --locale=fr_FR

  6. Traduzir catálogos de mensagens para cada idioma manualmente

  7. Compile catálogos de mensagens em arquivos *.mo, por exemplo via Babel:

    $ pybabel compile --directory=src/locale --domain=myextension

  8. Certifique-se de que os arquivos do catálogo de mensagens sejam distribuídos quando seu pacote for instalado, adicionando uma linha equivalente em sua extensão MANIFEST.in:

    MANIFEST.in
    recursive-include src *.pot *.po *.mo

Quando as mensagens em sua extensão foram alteradas, você também precisa atualizar o modelo de catálogo de mensagens e os catálogos de mensagens, por exemplo, via Babel:

$ pybabel extract --output=src/locale/myextension.pot src/
$ pybabel update --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale