API¶

Todos os nomes abaixo são exportados por gettext_tstrings. Nenhum outro nome é público. Esta página é a referência de assinaturas; para exemplos práticos de cada função, consulte o guia.

Tradução¶

Cada função recebe sua t-string de forma posicional e aceita translations e strict como argumentos nomeados (veja o guia).

Função	Assinatura
`gettext`	`(template, /, *, translations=None, strict=False) -> str`
`ngettext`	`(singular, plural, n, /, *, translations=None, strict=False) -> str`
`pgettext`	`(context, template, /, *, translations=None, strict=False) -> str`
`npgettext`	`(context, singular, plural, n, /, *, translations=None, strict=False) -> str`
`tr`	alias de `gettext`
`ntr`	alias de `ngettext`

`Translator`¶

Dataclass frozen que vincula um objeto de tradução:

Translator(translations, strict=False)

É chamável (_(t"…")) e fornece gettext, ngettext, pgettext, npgettext, tr e ntr.

Vínculo de contexto¶

Nome	Função
`use_translations(translations)`	Vincula durante um bloco `with` e restaura ao final.
`set_translations(translations)`	Vincula sem bloco em ciclos gerenciados pelo framework.
`get_translations()`	Lê o vínculo atual ou devolve `None`.

O vínculo usa ContextVar e é seguro em concorrência.

Strings preguiçosas¶

Nome	Função
`lazy_gettext(template, /, *, strict=False)`	Adia a tradução até cada renderização.
`lazy_pgettext(context, template, /, *, strict=False)`	Variante com contexto.
`LazyString`	O que ambas devolvem. Renderiza por `str()` e `format()` no idioma que estiver vinculado naquele momento, compara-se ao texto renderizado e não é hashable de propósito.

Exemplos trabalhados, inclusive por que o strict pertence à definição, estão em Tradução preguiçosa.

Baixo nível¶

`compile_template(template, /) -> CompiledTemplate`¶

Compila uma t-string reutilizando seu plano estático em cache.

`CompiledTemplate`¶

Membro	Significado
`.msgid`	Identificador gettext estável.
`.placeholders`	Nomes na ordem da primeira ocorrência.
`.render(pattern)`	Valida e renderiza; sempre lança em caso de diferença.

Tipos e erros¶

`Translations`¶

Um Protocol runtime_checkable para os quatro métodos padrão:

class Translations(Protocol):
    def gettext(self, message: str, /) -> str: ...
    def ngettext(self, singular: str, plural: str, n: int, /) -> str: ...
    def pgettext(self, context: str, message: str, /) -> str: ...
    def npgettext(self, context: str, singular: str, plural: str, n: int, /) -> str: ...

gettext.NullTranslations, gettext.GNUTranslations e Translations do Babel atendem ao protocolo.

Exceções¶

Classe	Quando
`TStringError`	Classe base.
`InvalidTemplateError`	A t-string de origem viola a convenção.
`InvalidTranslationError`	A tradução viola a convenção; o modo flexível registra e renderiza a origem.

Entry points de extração¶

Grupo	Nome	Usado por
`babel.extractors`	`gettext_tstrings`	`method` no `babel.cfg`
`babel.checkers`	`gettext_tstrings`	automaticamente por `pybabel compile`

Desempenho¶

O relato completo — o que é cacheado, quais são as chaves dos caches e os números medidos — está em O caminho quente. A versão curta: a validação é cacheada, nunca pulada, e a renderização inteira custa uma fração de microssegundo. Execute o benchmark no seu próprio alvo:

uv run python benchmarks/runtime.py