phoenix_title wx.Translations

This class allows getting translations for strings.

In wxWidgets this class manages message catalogs which contain the translations of the strings used to the current language. Unlike wx.Locale, it isn’t bound to locale. It can be used either independently of, or in conjunction with wx.Locale. In the latter case, you should initialize wx.Locale (which creates wx.Translations instance) first; in the former, you need to create a wx.Translations object and Set it manually.

Only one wx.Translations instance is active at a time; it is set with the Set method and obtained using Get.

Unlike wx.Locale, wx.Translations’ primary mean of identifying language is by its “canonical name”, i.e. ISO 639 code, possibly combined with ISO 3166 country code and additional modifiers (examples include “fr”, “en_GB” or “ca@valencia”; see wx.Locale.GetCanonicalName for more information). This allows apps using wx.Translations API to use even languages not recognized by the operating system or not listed in Language enum.

New in version 2.9.1.


class_hierarchy Class Hierarchy

Inheritance diagram for class Translations:

method_summary Methods Summary

__init__

Constructor.

AddCatalog

Add a catalog for use with the current locale.

AddStdCatalog

Add standard wxWidgets catalogs (“wxstd” and possible port-specific catalogs).

Get

Returns current translations object, may return None.

GetAvailableTranslations

Returns list of all translations of domain that were found.

GetBestTranslation

Returns the best UI language for the domain.

GetHeaderValue

Returns the header value for header header.

GetTranslatedString

Retrieves the translation for a string in all loaded domains unless the domain parameter is specified (and then only this catalog/domain is searched).

IsLoaded

Check if the given catalog is loaded, and returns True if it is.

Set

Sets current translations object.

SetLanguage

Sets translations language to use.

SetLoader

Changes loader use to read catalogs to a non-default one.


api Class API

class wx.Translations(object)

Possible constructors:

Translations()

This class allows getting translations for strings.


Methods

__init__(self)

Constructor.



AddCatalog(self, domain, msgIdLanguage=LANGUAGE_ENGLISH_US)

Add a catalog for use with the current locale.

By default, it is searched for in standard places (see wx.FileTranslationsLoader), but you may also prepend additional directories to the search path with wx.FileTranslationsLoader.AddCatalogLookupPathPrefix .

All loaded catalogs will be used for message lookup by GetString() for the current locale.

By default, i.e. if msgIdLanguage is not given, msgid strings are assumed to be in English and written only using 7-bit ASCII characters. If you have to deal with non-English strings or 8-bit characters in the source code, see the instructions in Writing Non-English Applications.

Parameters
  • domain (string) – The catalog domain to add.

  • msgIdLanguage (Language) – Specifies the language of “msgid” strings in source code (i.e. arguments to GetString(), wx.GetTranslation and the wx._ macro). It is used if AddCatalog cannot find any catalog for current language: if the language is same as source code language, then strings from source code are used instead.

Return type

bool

Returns

True if catalog was successfully loaded, False otherwise (which might mean that the catalog is not found or that it isn’t in the correct format).



AddStdCatalog(self)

Add standard wxWidgets catalogs (“wxstd” and possible port-specific catalogs).

Return type

bool

Returns

True if a suitable catalog was found, False otherwise

See also

AddCatalog



static Get()

Returns current translations object, may return None.

You must either call this early in app initialization code, or let wx.Locale do it for you.

Return type

wx.Translations



GetAvailableTranslations(self, domain)

Returns list of all translations of domain that were found.

This method can be used e.g. to populate list of application’s translations offered to the user. To do this, pass the app’s main catalog as domain.

Parameters

domain (string) –

Return type

list of strings



GetBestTranslation(self, *args, **kw)

Returns the best UI language for the domain.

The language is determined from the preferred UI language or languages list the user configured in the OS. Notice that this may or may not correspond to the default locale as obtained from wx.Locale.GetSystemLanguage ; modern operation systems (Windows Vista+, macOS) have separate language and regional (= locale) settings.

Parameters
  • domain (string) – The catalog domain to look for.

  • msgIdLanguage (Language) – Specifies the language of “msgid” strings in source code (i.e. arguments to GetString(), wx.GetTranslation and the wx._ macro).

Returns

Language code if a suitable match was found, empty string otherwise.

New in version 2.9.5.

overload Overloaded Implementations:



GetBestTranslation (self, domain, msgIdLanguage)

Parameters
  • domain (string) – The catalog domain to look for.

  • msgIdLanguage (Language) – Specifies the language of “msgid” strings in source code (i.e. arguments to GetString(), wx.GetTranslation and the wx._ macro).

Return type

string



GetBestTranslation (self, domain, msgIdLanguage=”en”)

Parameters
  • domain (string) – The catalog domain to look for.

  • msgIdLanguage (string) – Specifies the language of “msgid” strings in source code (i.e. arguments to GetString(), wx.GetTranslation and the wx._ macro).

Return type

string





GetHeaderValue(self, header, domain="")

Returns the header value for header header.

The search for header is case sensitive. If a domain is passed, this domain is searched. Else all domains will be searched until a header has been found.

The return value is the value of the header if found. Else this will be empty.

Parameters
  • header (string) –

  • domain (string) –

Return type

string



GetTranslatedString(self, *args, **kw)

overload Overloaded Implementations:



GetTranslatedString (self, origString, domain=””)

Retrieves the translation for a string in all loaded domains unless the domain parameter is specified (and then only this catalog/domain is searched).

Returns None if translation is not available.

This function is thread-safe.

Parameters
  • origString (string) –

  • domain (string) –

Return type

string

New in version 3.0.

Note

Domains are searched in the last to first order, i.e. catalogs added later override those added before.



GetTranslatedString (self, origString, n, domain=””)

Retrieves the translation for a string in all loaded domains unless the domain parameter is specified (and then only this catalog/domain is searched).

Returns None if translation is not available.

This form is used when retrieving translation of string that has different singular and plural form in English or different plural forms in some other language.

Parameters
  • origString (string) – The singular form of the string to be converted.

  • n – The number on which the plural form choice depends on. (In some languages, there are different plural forms for e.g. n=2 and n=3 etc., in addition to the singular form (n=1) being different.)

  • domain (string) – The only domain (i.e. message catalog) to search if specified. By default this parameter is empty, indicating that all loaded catalogs should be searched.

Return type

string

wx.GetTranslation function and wx._ macro.

This function is thread-safe.

New in version 3.0.

Note

Domains are searched in the last to first order, i.e. catalogs added later override those added before.





IsLoaded(self, domain)

Check if the given catalog is loaded, and returns True if it is.

According to GNU gettext tradition, each catalog normally corresponds to ‘domain’ which is more or less the application name.

Parameters

domain (string) –

Return type

bool

See also

AddCatalog



static Set(t)

Sets current translations object.

Deletes previous translation object and takes ownership of t.

Parameters

t (wx.Translations) –



SetLanguage(self, *args, **kw)

overload Overloaded Implementations:



SetLanguage (self, lang)

Sets translations language to use.

wx.LANGUAGE_DEFAULT has special meaning: best suitable translation, given user’s preference and available translations, will be used.

Parameters

lang (Language) –



SetLanguage (self, lang)

Sets translations language to use.

Empty lang string has the same meaning as wx.LANGUAGE_DEFAULT in SetLanguage : best suitable translation, given user’s preference and available translations, will be used.

Parameters

lang (string) –





SetLoader(self, loader)

Changes loader use to read catalogs to a non-default one.

Deletes previous loader and takes ownership of loader.

Parameters

loader (wx.TranslationsLoader) –

See also

wx.TranslationsLoader, wx.FileTranslationsLoader, ResourceTranslationsLoader