API¶

Wszystko poniżej jest eksportowane z gettext_tstrings. Nic innego nie jest publiczne. Ta strona to spis sygnatur; opracowane przykłady każdej funkcji znajdziesz w przewodniku.

Tłumaczenie¶

Każda funkcja przyjmuje swój t-string pozycyjnie i akceptuje dwa argumenty nazwane: translations (wracający do wiązania kontekstowego, a potem do globalnych funkcji biblioteki standardowej) i strict (patrz Przewodnik).

Funkcja	Sygnatura
`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 `gettext`
`ntr`	alias `ngettext`

`Translator`¶

Zamrożona dataclass wiążąca jeden obiekt tłumaczeń, żeby miejsca wywołań go nie powtarzały.

Translator(translations, strict=False)

Jest wywoływalna (_(t"…")) i niesie gettext, ngettext, pgettext, npgettext oraz aliasy tr / ntr.

Wiązanie kontekstu¶

Nazwa	Cel
`use_translations(translations)`	Zwiąż na czas bloku `with`, potem przywróć.
`set_translations(translations)`	Zwiąż bez bloku, dla cykli życia zarządzanych przez framework.
`get_translations()`	Odczytaj bieżące wiązanie albo `None`.

Wiązanie jest ContextVar, więc jest per kontekst i bezpieczne przy współbieżności.

Łańcuchy odroczone¶

Nazwa	Cel
`lazy_gettext(template, /, *, strict=False)`	Odrocz tłumaczenie do każdego renderowania.
`lazy_pgettext(context, template, /, *, strict=False)`	Forma z kontekstem.
`LazyString`	To, co obie zwracają. Renderuje się przez `str()` i `format()` w języku związanym w danym momencie, jest równy swojemu wyrenderowanemu tekstowi i celowo niehashowalny.

Przykłady z omówieniem — w tym wyjaśnienie, dlaczego strict należy do miejsca definicji — znajdziesz w rozdziale Tłumaczenie odroczone.

Niższy poziom¶

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

Skompiluj t-string, wykorzystując jego zbuforowany plan statyczny.

`CompiledTemplate`¶

Składnik	Znaczenie
`.msgid`	Stabilny identyfikator komunikatu gettext.
`.placeholders`	Nazwy symboli zastępczych w kolejności pierwszego wystąpienia.
`.render(pattern)`	Zwaliduj jeden wzorzec i wyrenderuj go. Przy niedopasowaniu zawsze zgłasza wyjątek.

Typy i błędy¶

`Translations`¶

runtime_checkable Protocol dla czterech standardowych metod, wszystkich wyłącznie pozycyjnych:

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 i Translations z Babel wszystkie go spełniają.

Wyjątki¶

Klasa	Zgłaszana gdy
`TStringError`	Klasa bazowa dla obu poniższych.
`InvalidTemplateError`	Źródłowy t-string łamie konwencję — złożona interpolacja albo powtórzona nazwa z innym formatowaniem.
`InvalidTranslationError`	Robi to tłumaczenie. W domyślnym trybie łagodnym jest to logowane, a zamiast tego renderowany jest tekst źródłowy.

Punkty wejścia ekstrakcji¶

Rejestrowane automatycznie przy instalacji; odwołujesz się do nich po nazwie, nie przez import.

Grupa	Nazwa	Używane przez
`babel.extractors`	`gettext_tstrings`	`method` w `babel.cfg`.
`babel.checkers`	`gettext_tstrings`	`pybabel compile`, automatycznie.

Wydajność¶

Pełny rachunek — co jest buforowane, po czym kluczują pamięci podręczne i zmierzone liczby — to Gorąca ścieżka. Wersja skrócona: walidacja jest buforowana, nigdy pomijana, a całe renderowanie kosztuje ułamek mikrosekundy. Uruchom benchmark na własnym celu:

uv run python benchmarks/runtime.py