Localization

This capability documents one focused aspect of the widget interface (Tk/Tcl-style behavior + bootstack extensions).

Note: You typically won’t use bootstack.core.capabilities.localization directly. This page describes the behavior that widgets expose.

Localization capability for bootstack widgets.

This module provides the core framework service for localizing widget text and values. It handles text resolution, value formatting, and locale change propagation.

The widget mixin (LocalizationMixin) delegates to these functions to remain a thin glue layer.

resolve_text

resolve_text(
    value: Any, *, localize_mode: bool | str = True
) -> LocalizedTextSpec | None

Resolve a text value into a LocalizedTextSpec.

This function handles the logic for creating localization specs from string values based on the localization mode.

Parameters:

Name	Type	Description	Default
`value`	`Any`	The value to resolve. Can be: - A LocalizedSpec: returned as-is (if it's a LocalizedTextSpec) - A string: wrapped in LocalizedTextSpec if localize_mode is truthy - None or empty string: returns None	required
`localize_mode`	`bool \| str`	Controls auto-wrapping of literals: - True or "auto": wrap strings in LocalizedTextSpec - False: return None (no localization)	`True`

Returns:

Type	Description
`LocalizedTextSpec \| None`	A LocalizedTextSpec if the value should be localized, None otherwise.

Examples:

>>> spec = resolve_text("Hello World")
>>> spec.key
'Hello World'

>>> spec = resolve_text("Hello", localize_mode=False)
>>> spec is None
True

>>> from bootstack.core.localization.specs import L
>>> spec = resolve_text(L("greeting"))
>>> spec.key
'greeting'

resolve_variable_text

resolve_variable_text(
    value: Any,
    *,
    value_format: str | None = None,
    default_format: str = "decimal",
) -> LocalizedValueSpec | None

Resolve a non-string value into a LocalizedValueSpec for formatting.

This function handles the logic for creating value formatting specs from numeric or other values.

Parameters:

Name	Type	Description	Default
`value`	`Any`	The value to format. Should be a number, date, or other formattable type.	required
`value_format`	`str \| None`	The IntlFormatter spec (e.g., "currency", "decimal", "percent"). If None, uses default_format.	`None`
`default_format`	`str`	Fallback format spec when value_format is None.	`'decimal'`

Returns:

Type	Description
`LocalizedValueSpec \| None`	A LocalizedValueSpec if the value can be formatted, None otherwise.

Examples:

>>> spec = resolve_variable_text(1234.56, value_format="currency")
>>> spec.value
1234.56
>>> spec.format_spec
'currency'

>>> spec = resolve_variable_text(0.5, value_format="percent")
>>> spec.format_spec
'percent'

apply_spec

apply_spec(
    spec: LocalizedSpec, locale: str | None = None
) -> str

Apply a localization spec and return the resolved string.

Parameters:

Name	Type	Description	Default
`spec`	`LocalizedSpec`	The LocalizedSpec to resolve.	required
`locale`	`str \| None`	The locale to use. If None, uses the current locale from MessageCatalog.	`None`

Returns:

Type	Description
`str`	The resolved, localized string value.

Examples:

>>> from bootstack.core.localization.specs import L, LV
>>> spec = L("hello")
>>> result = apply_spec(spec)  # Uses current locale
>>> isinstance(result, str)
True

>>> spec = LV(1234.56, "decimal")
>>> result = apply_spec(spec)
>>> isinstance(result, str)
True

get_current_locale

get_current_locale() -> str

Get the current locale from MessageCatalog.

Returns:

Type	Description
`str`	The current locale code (e.g., "en_US", "de_DE").

create_formatted_signal

create_formatted_signal(
    source_signal: "Signal[Any]", value_format: str
) -> tuple["Signal[str]", Any]

Create a formatted signal that tracks a source signal.

This creates a new Signal for formatted display that subscribes to the source signal and automatically formats values when they change.

Parameters:

Name	Type	Description	Default
`source_signal`	`'Signal[Any]'`	The source Signal to subscribe to.	required
`value_format`	`str`	The IntlFormatter spec for formatting values.	required

Returns:

Type	Description
`'Signal[str]'`	A tuple of (formatted_signal, formatter_callback) where:
`Any`	formatted_signal: A new Signal[str] containing the formatted value
`tuple['Signal[str]', Any]`	formatter_callback: The callback function for locale change updates

Examples:

>>> from bootstack.core.signals import Signal
>>> price = Signal(1234.56)
>>> formatted, formatter = create_formatted_signal(price, "currency")
>>> # formatted.get() returns locale-formatted currency string