Skip to content

MessageCatalog

Facade that unifies gettext and Tcl msgcat for bootstack.

Manages the active locale, a gettext translator, and runtime overrides. Translation prefers gettext when available and falls back to Tcl msgcat for both translation and printf-style formatting.

init staticmethod 

init(
    root: Tk | None = None,
    locales_dir: Union[str, Path, None] = None,
    domain: str = "messages",
    default_locale: str = "en",
    strip_ampersands: bool = True,
    emit_virtual_event: bool = True,
    virtual_event_name: str = "<<LocaleChanged>>",
) -> None

Initialize the translation system.

Parameters:

Name Type Description Default
root Tk | None

Optional Tk root to ensure msgcat is available.

 None
locales_dir Union[str, Path, None]

Base directory containing gettext catalogs (<lang>/LC_MESSAGES/<domain>.mo). If None, the directory is auto-discovered.

 None
domain str

Gettext domain name.

 'messages'
default_locale str

Locale to activate after initialization.

 'en'
strip_ampersands bool

If true, remove mnemonic & markers.

 True
emit_virtual_event bool

If true, generate a Tk virtual event after locale changes so widgets can refresh themselves.

 True
virtual_event_name str

The virtual event name to emit when the locale changes (default "<<LocaleChanged>>").

 '<<LocaleChanged>>'

__join staticmethod 

__join(*args: Any) -> str

Join format args for Tcl msgcat formatting.

Parameters:

Name Type Description Default
*args Any

Positional values to forward to Tcl 'format'.

 ()

Returns:

Type Description
str

String of brace-wrapped arguments joined by spaces.

translate staticmethod 

translate(src: str, *fmtargs: Any) -> str

Translate a message id according to the active locale.

Strategy: 1) If a runtime override exists and formatting args are provided, use Tcl msgcat so legacy '%1$s' placeholders work. 2) Otherwise use overrides (with Python '%' formatting when args are given). 3) Next, try gettext; if Python '%' formatting fails, fall back to Tcl formatting. 4) Finally, fall back entirely to Tcl msgcat.

Parameters:

Name Type Description Default
src str

Message id to translate.

 required
*fmtargs Any

Positional formatting values.

 ()

Returns:

Type Description
str

Localized and formatted string.

locale staticmethod 

locale(new_locale: Optional[str] = None) -> str

Get or set the current locale.

Parameters:

Name Type Description Default
new_locale Optional[str]

If provided, switch both gettext and msgcat locales.

 None

Returns:

Type Description
str

The active normalized locale code (or Tcl's current code when
str

queried).

preferences staticmethod 

preferences() -> list[str]

Return Tcl msgcat locale preferences (ordered).

load staticmethod 

load(dirname: Union[str, PathLike[str]]) -> int

Load Tcl .msg catalogs from a directory.

Parameters:

Name Type Description Default
dirname Union[str, PathLike[str]]

Directory containing msgcat .msg files.

 required

Returns:

Type Description
int

Number of files loaded, as reported by Tcl.

set staticmethod 

set(
    locale: str, src: str, translated: Optional[str] = None
) -> None

Define a single runtime translation and mirror it into msgcat.

Parameters:

Name Type Description Default
locale str

Target locale code.

 required
src str

Message id.

 required
translated Optional[str]

Localized string.

 None

set_many staticmethod 

set_many(locale: str, *args: str) -> int

Bulk-define runtime translations and mirror into msgcat.

Parameters:

Name Type Description Default
locale str

Target locale code.

 required
*args str

Alternating message ids and translations.

 ()

Returns:

Type Description
int

Number of messages set, as reported by Tcl.