ae.i18n
internationalization / localization helpers
on importing this portion it will automatically determine the default locale (language) and encoding of your operating system and user configuration.
the functions default_language()
and default_encoding()
- provided by this portion - are determining or
changing the default language and translation texts encoding.
additional languages will be automatically loaded by the function load_language_texts()
.
translation texts locale paths
multiple paths can be provided by your app as well as any python package and namespace portion to store translation
texts. by default they are situated in a sub-folder with the name loc underneath of your app/package root folder. to
load them call the function register_package_translations()
from the module using the locale texts.
Hint
see e.g. the ae namespace portion ae.gui_help
loading package/module specific translation messages.
Hint
the on_app_build()
app event is used by gui_help
to load the app-specific translation
texts on app startup.
to specify additional locale folders you can use the function register_translations_path()
.
in a locale folder have to exist at least one sub-folder with a name of the language code for each supported language (e.g. ‘loc/en’ for english).
in each of these sub-folders at least one message translation file with a file name ending in the string specified by
the constant MSG_FILE_SUFFIX
has to exist.
translatable message texts and f-strings
simple message text strings can be enclosed in the code of your application with the get_text()
function provided
by this portion/module:
from ae.i18n import get_text
message = get_text("any translatable message displayed to the app user.")
print(message) # prints the translated message text
for more complex messages with placeholders you can use the get_f_string()
function:
from ae.i18n import get_f_string
my_var = 69
print(get_f_string("The value of my_var is {my_var}."))
translatable message can also be provided in various pluralization forms. to get a pluralized message you have to pass
the count
keyword argument of get_text()
:
print(get_text("child", count=1)) # translated into "child" (in english) or e.g. "Kind" in german
print(get_text("child", count=3)) # -> "children" (in english) or e.g. "Kinder" (in german)
for pluralized message translated by the get_f_string()
function, the count value have to be passed in the count
item of the loc_vars
:
print(get_f_string("you have {count] children", loc_vars=dict(count=1)))
# -> "you have 1 child" or e.g. "Sie haben 1 Kind"
print(get_f_string("you have {count] children", loc_vars={'count': 3}))
# -> "you have 3 children" or "Sie haben 3 Kinder"
you can load several languages into your app run-time. to get the translation for a language that is not the current
default language you have to pass the language
keyword argument with the desired language code
onto the call of get_text()
(or get_f_string()
):
print(get_text("message", language='es')) # returns the spanish translation text of "message"
print(get_text("message", language='de')) # returns the german translation text of "message"
the helper function translation()
can be used to determine if a translation exists for a message text.
Hint
the ae portion ae.kivy.i18n
is implementing translation messages for kv files and provides additional
helper functions and methods.
Module Attributes
type of message literals in translation text files |
|
type of the data structure storing the loaded messages |
|
encoding of the messages in your app code |
|
language code of the messages in your app code |
|
message text translations of all loaded languages |
|
name suffix of translation text files |
|
file paths to search for translations |
|
language and encoding code of the current language/locale |
Functions
|
get and optionally set the default message text encoding. |
|
get and optionally set the default language code. |
|
translate passed f-string into a message string of the passed / default language. |
|
translate passed text string into the current language. |
|
load file content encoded with the given encoding into the specified language. |
|
load translation texts for the given language and optional domain. |
|
convert number in |
call from module scope of the package to register/add translations resources path. |
|
|
add/register the passed root path as new resource of translation texts. |
|
determine translation for passed text string and language. |
- LanguageMessages
type of the data structure storing the loaded messages
- DEF_ENCODING = 'UTF-8'
encoding of the messages in your app code
- DEF_LANGUAGE = 'en'
language code of the messages in your app code
- LOADED_TRANSLATIONS: Dict[str, Dict[str, str | Dict[str, str]]] = {}
message text translations of all loaded languages
- MSG_FILE_SUFFIX = 'Msg.txt'
name suffix of translation text files
- TRANSLATIONS_PATHS: List[str] = ['/home/docs/checkouts/readthedocs.org/user_builds/ae/envs/latest/lib/python3.9/site-packages/ae/gui_help/loc', '/home/docs/checkouts/readthedocs.org/user_builds/ae/envs/latest/lib/python3.9/site-packages/ae/kivy_qr_displayer/loc', '/home/docs/checkouts/readthedocs.org/user_builds/ae/envs/latest/lib/python3.9/site-packages/ae/kivy_sideloading/loc']
file paths to search for translations
- default_locale: List[str] = ['en', 'UTF-8']
language and encoding code of the current language/locale
- get_text(text, count=None, key_suffix='', language='')[source]
translate passed text string into the current language.
- Parameters:
count¶ (
Optional
[int
]) – pass int value if the translated text has variants for their pluralization. the count value will be converted into an amount/pluralize key by the functionplural_key()
.key_suffix¶ (
str
) – suffix to the key used if the translation is a dict.language¶ (
str
) – language code to load (def=current language code in 1st item ofdefault_locale
).
- Return type:
- Returns:
translated text message or the value passed into
text
if no translation text got found for the current language.
- get_f_string(f_str, key_suffix='', language='', glo_vars=None, loc_vars=None)[source]
translate passed f-string into a message string of the passed / default language.
- Parameters:
key_suffix¶ (
str
) – suffix to the key used if the translation is a dict.language¶ (
str
) – language code to load (def=current language code in 1st item ofdefault_locale
).glo_vars¶ (
Optional
[Dict
[str
,Any
]]) – global variables used in the conversion of the f-string expression to a string. the globals() of the caller of the callee will be available too and get overwritten by the items of this argument.loc_vars¶ (
Optional
[Dict
[str
,Any
]]) – local variables used in the conversion of the f-string expression to a string. the locals() of the caller of the callee will be available too and get overwritten by the items of this argument. pass a numeric value in the count item of this dict for pluralized translated texts (see alsocount
parameter of the functionget_text()
).
- Return type:
- Returns:
translated text message including evaluated and formatted variables/expressions of the f-string passed-in
f_str
. if no translation text got found for the current language then the original text message will be returned. any syntax errors and exceptions occurring in the conversion of the f-string are silently ignored.
- load_language_file(file_name, encoding, language)[source]
load file content encoded with the given encoding into the specified language.
- load_language_texts(language='', encoding='', domain='', reset=False)[source]
load translation texts for the given language and optional domain.
- Parameters:
language¶ (
str
) – language code of the translation texts to load. use the default language if not passed.domain¶ (
str
) – optional domain id, e.g. the id of an app, attached process or a user. if passed then it will be used as prefix for the message file name to be loaded additionally and after the default translation texts get loaded (overwriting the default translations).reset¶ (
bool
) – pass True to clear all previously added language/locale messages.
- Return type:
- Returns:
language code of the loaded/default language.
- plural_key(count)[source]
convert number in
count
into a dict key to access the correct plural form.
- register_package_translations()[source]
call from module scope of the package to register/add translations resources path.
no parameters needed because we use here
stack_var()
helper function to determine the the module file path via the __file__ module variable of the caller module in the call stack. in this call we have to overwrite the default value (SKIPPED_MODULES
) of theskip_modules
parameter to not skip ae portions that are providing package resources and are listed in theSKIPPED_MODULES
, like e.g.ae.gui_app
andae.gui_help
(passing empty string ‘’ to overwrite default skip list).
- register_translations_path(translation_path='')[source]
add/register the passed root path as new resource of translation texts.