peng3d.i18n - Lightweight Translation Manager

class peng3d.i18n.TranslationManager(peng: peng3d.Peng)

Manages sets of translation files in multiple languages.

This Translation System uses language codes to identify languages, there is no requirement to follow a specific standard, but it is recommended to use simple 2-digit codes like en and de, adding an underscore to define sub-languages like en_gb and en_us.

Whenever a new translation file is needed, it will be parsed and then cached. This speeds up access times and also practically eliminates load times when switching languages.

Several events are sent by this class, see peng3d:i18n.* Events Category.

Most of these events are also sent as actions, these actions are described in the methods that cause them.

There are also severale config options that determine the behaviour of this class. See Translation Options for more information.

This Manager requires the ResourceManager() to be already initialized.

discoverLangs(domain: str = '*') → List[str]

Generates a list of languages based on files found on disk.

The optional domain argument may specify a domain to use when checking for files. By default, all domains are checked.

This internally uses the glob built-in module and the i18n.lang.format config option to find suitable filenames. It then applies the regex in i18n.discover_regex to extract the language code.

loadDomain(domain: str, lang: Optional[str] = None, encoding: str = 'utf-8') → bool

Loads the translation data of a single domain for a specific language from disk into the cache.

If no language was given, the current language is used.

If the translation file could not be found or any errors occur while reading it, these errors will be silently discarded, only recognizable by a return value of False.

If the load was successful, the action loaddomain will be executed and this method will return True.

setLang(lang: str) → None

Sets the default language for all domains.

For recommendations regarding the format of the language code, see TranslationManager.

Note that the lang parameter of both translate() and translate_lazy() will override this setting.

Also note that the code won’t be checked for existence or plausibility. This may cause the fallback strings to be displayed instead if the language does not exist.

Calling this method will cause the setlang action and the :peng3d:event`peng3d:i18n.set_lang` event to be triggered. Note that both action and event will be triggered even if the language did not actually change.

This method also automatically updates the i18n.lang config value.

t(key: str, translate: bool = True, lang: Optional[str] = None) → str

Translates the given key.

If no language was given, the language last passed to setLang() will be used.

If the translation key could not be found (e.g. because the language code is invalid), the key itself will be returned.

Note that this method returns a string and thus does not have any way to modify the returned value if the language is changed by the user. If dynamic translation is required, translate_lazy() should be used instead.

tl(key: str, data: Optional[Dict[KT, VT]] = None, translate: bool = True, lang: Optional[str] = None) → peng3d.i18n._LazyTranslator

Lazily translates a given translation key.

This method is similar to translate(), but returns a special object rather than a string. This allows for on-the-fly changing of the language without having to re-set all the places where translated strings are used.

Whenever the returned object is converted to a string by str() or repr() or is formatted using either the old %-notation or the newer str.format(), the translation key will be looked up again, in case the language has changed.

Note that this requires support from the widgets (or other consumers of the returned value), namely that they only convert to string just prior to rendering and re-render either regularly or whenever either the setlang action or the peng3d:i18n.set_lang event is called.

Most built-in widgets support this, but some special cases are not supported yet. For example, setting the window title dynamically requires using the caption_t parameter instead of the raw caption parameter.

translate(key: str, translate: bool = True, lang: Optional[str] = None) → str

Translates the given key.

If no language was given, the language last passed to setLang() will be used.

If the translation key could not be found (e.g. because the language code is invalid), the key itself will be returned.

Note that this method returns a string and thus does not have any way to modify the returned value if the language is changed by the user. If dynamic translation is required, translate_lazy() should be used instead.

translate_lazy(key: str, data: Optional[Dict[KT, VT]] = None, translate: bool = True, lang: Optional[str] = None) → peng3d.i18n._LazyTranslator

Lazily translates a given translation key.

This method is similar to translate(), but returns a special object rather than a string. This allows for on-the-fly changing of the language without having to re-set all the places where translated strings are used.

Whenever the returned object is converted to a string by str() or repr() or is formatted using either the old %-notation or the newer str.format(), the translation key will be looked up again, in case the language has changed.

Note that this requires support from the widgets (or other consumers of the returned value), namely that they only convert to string just prior to rendering and re-render either regularly or whenever either the setlang action or the peng3d:i18n.set_lang event is called.

Most built-in widgets support this, but some special cases are not supported yet. For example, setting the window title dynamically requires using the caption_t parameter instead of the raw caption parameter.