Localization#

ttkbootstrap translates its built-in strings — dialog buttons, date names, and the like — through Tk’s message catalog. L looks up a translation, set_locale switches the active locale, LocaleVar is a variable that re-translates itself when the locale changes, and MessageCatalog is the lower-level catalog API. The Localization guide shows them in use.

L(src, *args, **kwargs)#

Translate src for the current locale, then Python-str.format it.

The universal i18n idiom (_()), resolved at call time – correct for the common “pick the locale at startup” case. Uses Python str.format ({} / {0} / {name} fields), sidestepping the Tcl format path; for %-style specifiers use MessageCatalog.translate instead.

Parameters:
Return type:

str

set_locale(locale)#

Set the application locale.

Called before App() exists, the locale is queued and applied when the root is created (the intended top-of-file use). If a root already exists it applies immediately, emitting <<LocaleChanged>> so live LocaleVar variables re-translate.

Parameters:

locale (str)

Return type:

None

class LocaleVar(master=None, src='', *args, name=None, **kwargs)#

Bases: StringVar

A StringVar that re-translates its source on <<LocaleChanged>>.

Hold a source string and show its translation for the current locale; pass it as textvariable= to any (vanilla or themed) widget for live language switching – when set_locale(...) changes the locale, the variable re-translates itself. Format args, if any, are applied with Python str.format (like L).

Every live LocaleVar is driven by a single <<LocaleChanged>> binding on the application root (where locale() generates the event), regardless of the variable’s own master. The registry holds only weak references, so a dropped LocaleVar is collected without any cleanup call; use stop_tracking() to opt one out explicitly while keeping it alive.

Construct a string variable.

MASTER can be given as master widget. VALUE is an optional value (defaults to “”) NAME is an optional Tcl name (defaults to PY_VARnum).

If NAME matches an existing variable and VALUE is omitted then the existing value is retained.

Parameters:
set_source(src, *args, **kwargs)#

Replace the source string (and any format args) and re-translate now.

Parameters:
Return type:

None

stop_tracking()#

Stop re-translating on <<LocaleChanged>> (leaves it at its current value). Also happens automatically when the variable is garbage-collected.

Return type:

None

class MessageCatalog#

Bases: object

Static wrapper for the Tcl/Tk ::msgcat message catalog commands.

static load(dirname)#

Searches the specified directory for files that match the language specifications returned by preferences. Each file located is sourced.

Parameters:

dirname (str or Pathlike object) – The directory path of the msg files.

Returns:

int – Then number of message files which matched the specification and were loaded.

Return type:

int

static locale(newlocale=None)#

Sets the locale to newlocale. If newlocale is omitted, the current locale is returned, otherwise the current locale is set to newlocale. The initial locale defaults to the locale specified in the user’s environment.

Setting a new locale emits a <<LocaleChanged>> virtual event on the default root so live widgets can re-translate.

Parameters:

newlocale (str, optional) – The new locale code used to define the language for the application. Default is None.

Returns:

str – The current locale name if newlocale is None or an empty string.

Return type:

str

static max(*src)#

Given several source strings, max returns the length of the longest translated string. This is useful when designing localized GUIs, which may require that all buttons, for example, be a fixed width (which will be the width of the widest button).

Parameters:

*src (str) – A series of strings to compare

Returns:

int – The length of the longest str.

Return type:

int

static preferences()#

Returns an ordered list of the locales preferred by the user, based on the user’s language specification. The list is ordered from most specific to the least preference. If the user has specified LANG=en_US_funky, this method would return {en_US_funky en_US en}.

Returns:

list[str] – Locales preferred by the user.

Return type:

list[str]

static set(locale, src, translated=None)#

Sets the translation for ‘src’ to ‘translated’ in the specified locale. If translated is not specified, src is used for both.

Parameters:

  • locale (str) – The local code used when translating the src.

  • src (str) – The original language string.

  • translated (str, optional) – The translated string. Default is None, in which case src is used.

Return type:

None

static set_many(locale, *args)#

Sets the translation for multiple source strings in args in the specified locale and the current namespace. Must be an even number of args.

Parameters:

  • locale (str) – The local code used when translating the src.

  • *args (str) – A series of src, translated pairs.

Returns:

int – The number of translation sets.

Return type:

int

static translate(src, *fmtargs)#

Returns a translation of src according to the user’s current locale.

This is the main function used to localize an application. Instead of using an English string directly, an applicaton can pass the English string through translate and use the result. If an application is written for a single language in this fashion, then it is easy to add support for additional languages later simply by defining new message catalog entries.

Parameters:

  • src (str) – The string to be translated.

  • *fmtargs (Any, optional) – Extra arguments passed internally to the Tcl [format](https://www.tcl-lang.org/man/tcl/TclCmd/format.html) command (msgcat applies %-style specifiers). For the Python str.format idiom, use L instead.

Returns:

str – The translated string.

Return type:

str

See also#