Package: appstrings
Minimal string translation library for PythonIn summary:Developers reference translatable strings using identifiers in an enumeration class.Language-specific strings are written in several enumeration classes.The library transparently transforms string identifiers into already translated strings,
depending on the system locale or user-selected locale.This is neither a full internationalization library nor suitable for usual translation workflows.
Make sure it meets your needs.
If not, there are other libraries that do the job, for example,gettext.How to useTranslate text for each localeDefine all translatable strings in an enumeration class.
Those enumerations are calledtranslatorsin the context of this library.
Additionally:Youmustalso define a_langattribute and set its value
to the corresponding locale or language string.
A list of valid locale strings can be found atsaimana.com.Youshouldalso define a_domainattribute and set its value
to your application's name or any other random string. This prevents any conflict
with translators from other libraries (if any). If not given, current
module name is used, so you must create all your translators in the same module
in that case.For example:fromenumimportEnumclassEN(Enum):_lang="en"_domain="appstrings.example"TEST="Hello world!"classES_MX(Enum):_lang="es_MX"_domain="appstrings.example"TEST="¡Hola mundo!"Then, all translators must be "installed" at initialization:fromappstringsimportinstallinstall(EN)install(ES_MX)The library will check that all installed translators enumerate the same set of constants,
except for "sunder" and "dunder" ones.
Use that notation for non-translatable attributes if you need to. For example:classES_MX(Enum):_lang="es_MX"_domain="appstrings.example"_note="this is a developer note, not to be translated"TEST="¡Hola mundo!"Note that another library imported in your project may useappstringsas well, thus installing its own translators.
Use the_domainattribute to prevent any conflict.Use already translated textThe functiongettext()is used for translation. For example:fromappstringsimportgettextprint(gettext(EN.TEST))You may want to aliasgettextto_for convenience:_=gettextprint(_(EN.TEST))# Print translated string, depending on current localeThis way, you may disable translation at any time for development purposes:# _ = gettext_=lambdaid:id._value_print(_(EN.TEST))# Always print all strings in english, for nowThe library chooses the best-matching translator for the current translation locale, which is initialized fromlocale.getlocale().
You may force a specific locale for translation at any time:fromappstringsimportset_translation_localeset_translation_locale("es_MX")print(_(EN.TEST))# Prints text in spanish language of Mexicothen force the system locale again:set_translation_locale()Note that forcing a specific locale not available in your application will notmagicallytranslate your strings to that locale.Fallback to a default languageIn the previous examples, there is no translator for the localept_BR, to say one.
In such a case, the translator used ingettext()will work as thedefault languagefor non-translated locales.
In the early example, brazilian people would read the text in english.
However, ifprint(_(ES_MX.TEST))were used instead, brazilian people would read the text in spanish.The ability to change the default language at any time comes from aliases:STR=ENprint(_(STR.TEST))# Prints TEST string in english if there is no matching translatorSTR=ES_MXprint(_(STR.TEST))# Prints TEST string in spanish if there is no matching translatorThis approach is developer-friendly, but not user-friendly.Be user-friendlyYour application should allow the user to choose an available language
via command-line parameters, environment variables or other means.The functionget_installed_translators()will help in order to show a list of
available languages:print("Available languages/locales:")fortranslatoringet_installed_translators(STR._domain._value_):print(translator._lang._value_)Obviously, you already know which languages are available in your application,
but this approach ensures you don't have to modify your code after adding a new translator.Callset_translation_locale()to make effective the user preference.Organize your code for translationYou may spread your translators along many source files as long as your application imports and installs them.For example:flowchart TB
    main["__main__.py (your application)"]
    default["translation.py (defines default language)"]
    lang_es["translation_es.py (defines spanish translator)"]
    lang_pt["translation_pt.py (defines portuguese translator)"]

    main --imports--> default
    default --imports--> lang_es
    default --imports--> lang_ptBut the following schema will work just the same:flowchart TB
    main["__main__.py (your application)"]
    default["translation.py (defines default language)"]
    lang_es["translation_es.py (defines spanish translator)"]
    lang_pt["translation_pt.py (defines portuguese translator)"]

    main --imports--> default
    main --imports--> lang_es
    main --imports--> lang_ptThe "translation*.py" files would look like this:fromenumimportEnumfromappstringsimportinstallclassCertainTranslator(Enum):_lang=..._domain=...TEXT1=...TEXT2=......install(CertainTranslator)That is all about this library. As simple as that.TroubleshootingWhy some strings are properly translated, but not others?Ensure all your translators have a_domainattribute set to the very same value (case-sensitive).I get a TranslatorException :String ID XXX from YYYY is missing at ZZZZ. Why ?There are two possible reasons:One of your translators is missing a string that others have. Check.Your application is in conflict with some library. User another string int the "_domain" attribute.