translation module

Simplistic internationalization classes inspired by i18next.

Classes

class ctlbase.translation.TranslationManager(lng)

A translation manager for various languages.

For each target language, a JSON-formatted translation file must exist. The following is an example for de:

{
    "defaultVariables": {
        "source": "Signalquelle"
    },
    "SOURCE_SET_SUCCEEDED": "{{source}} gewählt.",
    "THREED_ON_SUCCEEDED": "3D-Modus eingeschaltet.",
    "THREED_OFF_SUCCEEDED": "3D-Modus ausgeschaltet.",
    "MODE_SET_SUCCEEDED": "Modus {{mode}} für {{timeout}} Sekunden gesetzt.",
    "MODE_UNSET_SUCCEEDED": "Modus {{mode}} zurückgenommen."
}

The syntax is a basic version of i18next. Each translation in the file is identified by an individual key. What is more, each translation may contain one or more variable names enclosed in double curly braces.

A variable name in turn can either be a numeric index or a semantic key:

"Modus {{0}} für {{1}} Sekunden gesetzt."
# or
"Modus {{mode}} für {{timeout}} Sekunden gesetzt."

At runtime, variables are replaced by their actual values. If, during the so-called interpolation, the value of an individual variable cannot be resolved, a possibly existing default value from the defaultVariables object is used.

Only one target language is active at a time. It can be changed via changeLanguage(). The actual translation of a str is done via translate().

__init__(lng)

Creates a translation manager with an initial target language.

Parameters:

lng (str) – Two-letter language code for the initial target language.

changeLanguage(lng)

Changes the target language for translations. Subsequent calls to translate() will use the new language unless overridden temporarily.

Parameters:

lng (str) – Two-letter language code for the new language.

loadLanguages(lngs, isForceReload=False)

(Pre)loads the translation files for one or more languagea.

The search path is determined by TRANSLATION_LOCATIONS. Below the search path, directories with two-letter language codes are expected, each containing a translation file named translation.json. A typical structure looks like this:

locales/
    de/
        translation.json
    fr/
        translation.json
    it/
        translation.json

Parameters:

• lngs (str | list[str] | tuple[str]) – One or more two-letter language codes for the translation files to load, e.g. de.

• isForceReload (bool) – If True, the translation file for a language is reloaded if it has been loaded already.

Raises:

• FileNotFoundError – If a translation file for at least one language cannot be found.

• json.JSONDecodeError – If at least one translation file does not contain a valid JSON document.

translate(key, replace, lng=None, debugOutput=None)

Looks up and interpolates a translation for a specific key.

Lazy-loads the translation file for the target language if it has not been loaded yet via loadLanguages().

For debugging purposes, messages are written to debugOutput in the following cases:

• If the value of a variable cannot be resolved.

Parameters:

• key (str) – The key to look up.

• replace (list | tuple | dict) – The variable values to interpolate. If the variable names are numeric indices, a list or tuple must be provided. If the variable names are semantic keys, a dict with those keys must be provided.

• lng (str | None) – A temporary override for the target language. If None, language is used.

• debugOutput (StringIO | None) – A string buffer for appending debug messages. If None, no messages are produced.

Raises:

• RuntimeError – If no target language is set.

• FileNotFoundError – If a translation file for the target language cannot be found. Only relevant when lazy-loading the translation file.

• json.JSONDecodeError – If the translation file does not contain a valid JSON document. Only relevant when lazy-loading the translation file.

• KeyError – If the key cannot be found in the translation file for the target language.

language: str

Two-letter language code for the target language.

Constants and defaults

ctlbase.translation.Translation = <ctlbase.translation.TranslationManager object>

Singleton for translations into the environment’s default language.