Uranium
Application Framework
Loading...
Searching...
No Matches
UM.i18n.i18nCatalog Class Reference

Public Member Functions

None __init__ (self, str name=None, str language="default")
bool hasTranslationLoaded (self)
str i18n (self, str text, *Any args)
str i18nc (self, str context, str text, *Any args)
str i18np (self, str single, str multiple, int counter, *Any args)
str i18ncp (self, str context, str single, str multiple, int counter, *Any args)
None setTagReplacements (cls, Dict[str, Optional[str]] replacements)
None setApplication (cls, "Application" application)
None setApplicationName (cls, str applicationName)
None setLanguage (cls, str language)

Protected Member Functions

str _replaceTags (self, str string)
None _update (self)

Detailed Description

Wraps a gettext translation catalog for simplified use.

This class wraps a gettext translation catalog to simplify its use.
It will load the translation catalog from Resources' i18nLocation
and allows specifying which language to load.

To use this class, create an instance of it with the name of the catalog
to load. Then call `i18n` or `i18nc` on the instance to perform a look
up in the catalog.

Standard Contexts and Translation Tags
--------------------------------------

The translation system relies upon a set of standard contexts and HTML-like
translation tags. Please see the [translation guide](docs/translations.md)
for details.

Constructor & Destructor Documentation

◆ __init__()

None UM.i18n.i18nCatalog.__init__ ( self,
str name = None,
str language = "default" )
Creates a new catalogue.

:param name: The name of the catalog to load.
:param language: The language to load. Valid values are language codes or
"default". When "default" is specified, the language to load will be
determined based on the system"s language settings.

:note When `language` is `default`, the language to load can be
overridden using the "LANGUAGE" environment variable.

Member Function Documentation

◆ _replaceTags()

str UM.i18n.i18nCatalog._replaceTags ( self,
str string )
protected
Replace formatting tags in the string with globally-defined replacement
values.

Which tags are replaced can be defined using the ``setTagReplacements``
method.

:param string: The text to replace tags in.
:return: The text with its tags replaced.

◆ _update()

None UM.i18n.i18nCatalog._update ( self)
protected
Fill the catalogue by loading the translated texts from file (again).

◆ hasTranslationLoaded()

bool UM.i18n.i18nCatalog.hasTranslationLoaded ( self)
Whether the translated texts are loaded into this catalogue.

If there are translated texts, it is safe to request the text with the
``gettext`` method and so on.

:return: ``True`` if texts are loaded into this catalogue, or ``False``
if they aren't.

◆ i18n()

str UM.i18n.i18nCatalog.i18n ( self,
str text,
*Any args )
Mark a string as translateable.

:param text: The string to mark as translatable
:param args: Formatting arguments. These will replace formatting elements
             in the translated string. See python str.format().
:return: The translated text or the untranslated text if no translation
was found.

◆ i18nc()

str UM.i18n.i18nCatalog.i18nc ( self,
str context,
str text,
*Any args )
Mark a string as translatable and provide a context for translators.

:param context: The context of the string, i.e. something that explains
the use of the text.
:param text: The text to mark translatable.
:param args: Formatting arguments. These will replace formatting elements
in the translated string. See python ``str.format()``.
:return: The translated text or the untranslated text if it was not found
in this catalog.

◆ i18ncp()

str UM.i18n.i18nCatalog.i18ncp ( self,
str context,
str single,
str multiple,
int counter,
*Any args )
Mark a string as translatable with plural forms and a context for
translators.

:param context: The context of this string.
:param single: The singular form of the string.
:param multiple: The plural form of the string.
:param counter: The value that determines whether the singular or plural
form should be used.
:param args: Formatting arguments. These will replace formatting elements
in the translated string. See python ``str.format()``.
:return: The translated string, or the untranslated text if no
translation could be found. Note that the fallback simply checks if
counter is greater than one and if so returns the plural form.

:note For languages other than English, more than one plural form might
exist. The counter is at all times used to determine what form to use,
with the language files specifying what plural forms are available.
Additionally, counter is passed as first argument to format the string.

◆ i18np()

str UM.i18n.i18nCatalog.i18np ( self,
str single,
str multiple,
int counter,
*Any args )
Mark a string as translatable with plural forms.

:param single: The singular form of the string.
:param multiple: The plural form of the string.
:param counter: The value that determines whether the singular or plural
form should be used.
:param args: Formatting arguments. These will replace formatting elements
in the translated string. See python ``str.format()``.
:return: The translated string, or the untranslated text if no
translation could be found. Note that the fallback simply checks if
counter is greater than one and if so, returns the plural form.

:note For languages other than English, more than one plural form might
exist. The counter is at all times used to determine what form to use,
with the language files specifying what plural forms are available.
Additionally, counter is passed as first argument to format the string.

◆ setApplication()

None UM.i18n.i18nCatalog.setApplication ( cls,
"Application" application )
Set the ``Application`` instance to request the language and application
name from.

:param application: The ``Application`` instance of the application that
is running.

◆ setTagReplacements()

None UM.i18n.i18nCatalog.setTagReplacements ( cls,
Dict[str, Optional[str]] replacements )
Change the global tags that are replaced in every internationalised
string.

If a text contains something of the form ``<key>`` or ``</key>``, then
the word ``key`` will get replaced by whatever is in this dictionary at
the specified key.

:param replacements: A dictionary of strings to strings, indicating which
words between tags should get replaced.

The documentation for this class was generated from the following file:
  • UM/i18n.py