API i18n¶
- sphinx.locale.init(locale_dirs: Iterable[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 oinit
reentrante).
- sphinx.locale.init_console(locale_dir: 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:
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 = os.path.abspath(os.path.dirname(__file__)) locale_dir = os.path.join(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
. Olanguage
é 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).
Extension internationalization (i18n
) and localization (l10n
) using i18n API¶
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:
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.
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:from sphinx.locale import get_translation MESSAGE_CATALOG_NAME = 'myextension' _ = get_translation(MESSAGE_CATALOG_NAME) translated_text = _('Hello Sphinx!')
Configure sua extensão para estar ciente de suas traduções dedicadas:
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)
Gere o arquivo modelo de catálogo de mensagens
*.pot
, geralmente no diretório fontelocale/
, por exemplo via Babel:$ pybabel extract --output=src/locale/myextension.pot src/
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
Traduzir catálogos de mensagens para cada idioma manualmente
Compile catálogos de mensagens em arquivos
*.mo
, por exemplo via Babel:$ pybabel compile --directory=src/locale --domain=myextension
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
: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