Localization (i18n)#

Localization helpers. Widget text is translated automatically when a translation is registered for the active locale; wrap a string with L to mark it translatable with interpolation, or a value with LV to format it for the locale. Register your own translations with the catalog functions below.

For a task-oriented introduction — automatic translation, registering strings, locale-aware dates and numbers, switching locale at runtime — see the Localization (i18n) guide.

Translatable text and values#

bootstack.i18n.L(key, *fmtargs, **fmtkwargs)#

Mark text as translatable, with optional {}-style interpolation.

The key is looked up in the translation catalog for the active locale, then formatted with Python str.format — so placeholders use {0} / {name} style. The spec re-resolves whenever the locale changes.

Parameters:

  • key (str) – The source string or message id to translate.

  • *fmtargs (Any) – Positional values for {0}, {1}, … placeholders.

  • **fmtkwargs (Any) – Named values for {name} placeholders.

Returns:

A LocalizedTextSpec you can pass anywhere a widget takes text.

Return type:

LocalizedTextSpec

Examples

>>> L("Hello, {0}", name)             # positional
>>> L("Hello, {name}", name=user)     # named
bootstack.i18n.LV(value, format_spec)#

Create a LocalizedValueSpec for locale-aware value formatting.

Shorthand constructor that creates a value formatting spec for numbers, dates, times, and currency values.

Parameters:

  • value (Any) – The value to format (number, date, datetime, time, etc.).

  • format_spec (str | Mapping[str, Any]) – IntlFormatter spec like “currency”, “decimal”, “percent”, or a dict with detailed formatting options.

Returns:

A LocalizedValueSpec instance.

Return type:

LocalizedValueSpec

Examples

>>> spec = LV(1234.56, "currency")
>>> # Will format as currency in the current locale

Extending the translation catalog#

bootstack.i18n.add_translation(locale, source, translated)#

Register a single translation for a locale.

Parameters:

  • locale (str) – Target locale code (e.g. 'es', 'fr', 'pt_BR').

  • source (str) – The source string (the message id), e.g. 'Save'.

  • translated (str) – The localized string, e.g. 'Guardar'.

bootstack.i18n.add_translations(locale, translations)#

Register multiple translations for a locale.

Parameters:

  • locale (str) – Target locale code (e.g. 'es').

  • translations (Mapping[str, str]) – A mapping of source string to localized string, e.g. {"Save": "Guardar", "Cancel": "Cancelar"}.

Returns:

The number of translations registered.

Return type:

int

bootstack.i18n.load_po(path, locale=None)#

Load translations from a gettext .po source file into the catalog.

The .po is read directly with Babel — no msgfmt compilation and no .mo files. The path is resolved in both a development run and a PyInstaller build (bundle the .po with your app, e.g. under assets/, which the default build config already includes).

Parameters:

  • path (str | PathLike[str]) – Path to a .po file, relative to the project or absolute.

  • locale (str | None) – Target locale code. If omitted, it is read from the .po file’s Language: header.

Returns:

The number of translations loaded.

Return type:

int

bootstack.i18n.load_translations(directory)#

Load translation catalogs from a directory of .msg files.

Each file is named for its locale (e.g. es.msg) and holds the locale’s translations. This is the bulk alternative to add_translations() for projects that keep translations in files.

Parameters:

directory (str | PathLike[str]) – Path to a directory containing .msg catalog files.

Returns:

The number of catalog files loaded.

Return type:

int