.. wxPython Phoenix documentation This file was generated by Phoenix's sphinx generator and associated tools, do not edit by hand. Copyright: (c) 2011-2020 by Total Control Software License: wxWindows License .. include:: headings.inc .. _wx.Translations: ========================================================================================================================================== |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 :ref:`wx.Locale`, it isn't bound to locale. It can be used either independently of, or in conjunction with :ref:`wx.Locale`. In the latter case, you should initialize :ref:`wx.Locale` (which creates :ref:`wx.Translations` instance) first; in the former, you need to create a :ref:`wx.Translations` object and :meth:`~wx.Translations.Set` it manually. Only one :ref:`wx.Translations` instance is active at a time; it is set with the :meth:`~wx.Translations.Set` method and obtained using :meth:`~wx.Translations.Get`. Unlike :ref:`wx.Locale`, :ref:`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 :meth:`wx.Locale.GetCanonicalName` for more information). This allows apps using :ref:`wx.Translations` API to use even languages not recognized by the operating system or not listed in Language enum. .. versionadded:: 2.9.1 .. seealso:: :ref:`wx.Locale`, :ref:`wx.TranslationsLoader`, :ref:`wx.FileTranslationsLoader` | |class_hierarchy| Class Hierarchy ================================= .. raw:: html
Inheritance diagram for class Translations:
| |method_summary| Methods Summary ================================ ================================================================================ ================================================================================ :meth:`~wx.Translations.__init__` Constructor. :meth:`~wx.Translations.AddCatalog` Add a catalog for use with the current locale. :meth:`~wx.Translations.AddStdCatalog` Add standard wxWidgets catalogs ("wxstd" and possible port-specific catalogs). :meth:`~wx.Translations.Get` Returns current translations object, may return ``None``. :meth:`~wx.Translations.GetAvailableTranslations` Returns list of all translations of `domain` that were found. :meth:`~wx.Translations.GetBestTranslation` Returns the best UI language for the `domain`. :meth:`~wx.Translations.GetHeaderValue` Returns the header value for header `header`. :meth:`~wx.Translations.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). :meth:`~wx.Translations.IsLoaded` Check if the given catalog is loaded, and returns ``True`` if it is. :meth:`~wx.Translations.Set` Sets current translations object. :meth:`~wx.Translations.SetLanguage` Sets translations language to use. :meth:`~wx.Translations.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. .. method:: __init__(self) Constructor. .. method:: 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 :ref:`wx.FileTranslationsLoader`), but you may also prepend additional directories to the search path with :meth:`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 :ref:`Writing Non-English Applications `. :param `domain`: The catalog domain to add. :type `domain`: string :param `msgIdLanguage`: Specifies the language of "msgid" strings in source code (i.e. arguments to GetString(), `wx.GetTranslation` and the `wx._` macro). It is used if :meth:`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. :type `msgIdLanguage`: wx.Language :rtype: `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). .. method:: AddStdCatalog(self) Add standard wxWidgets catalogs ("wxstd" and possible port-specific catalogs). :rtype: `bool` :returns: ``True`` if a suitable catalog was found, ``False`` otherwise .. seealso:: :meth:`AddCatalog` .. staticmethod:: Get() Returns current translations object, may return ``None``. You must either call this early in app initialization code, or let :ref:`wx.Locale` do it for you. :rtype: :ref:`wx.Translations` .. method:: 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`. :param `domain`: :type `domain`: string :rtype: `list of strings` .. seealso:: :meth:`GetBestTranslation` .. method:: 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 :meth:`wx.Locale.GetSystemLanguage` ; modern operation systems (Windows Vista+, macOS) have separate language and regional (= locale) settings. :param `domain`: The catalog domain to look for. :type `domain`: string :param `msgIdLanguage`: Specifies the language of "msgid" strings in source code (i.e. arguments to GetString(), `wx.GetTranslation` and the `wx._` macro). :type `msgIdLanguage`: wx.Language :returns: Language code if a suitable match was found, empty string otherwise. .. versionadded:: 2.9.5 |overload| Overloaded Implementations: :html:`

` **GetBestTranslation** `(self, domain, msgIdLanguage)` :param `domain`: The catalog domain to look for. :type `domain`: string :param `msgIdLanguage`: Specifies the language of "msgid" strings in source code (i.e. arguments to GetString(), `wx.GetTranslation` and the `wx._` macro). :type `msgIdLanguage`: wx.Language :rtype: `string` :html:`

` **GetBestTranslation** `(self, domain, msgIdLanguage="en")` :param `domain`: The catalog domain to look for. :type `domain`: string :param `msgIdLanguage`: Specifies the language of "msgid" strings in source code (i.e. arguments to GetString(), `wx.GetTranslation` and the `wx._` macro). :type `msgIdLanguage`: string :rtype: `string` :html:`

` .. method:: 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. :param `header`: :type `header`: string :param `domain`: :type `domain`: string :rtype: `string` .. method:: GetTranslatedString(self, *args, **kw) |overload| Overloaded Implementations: :html:`

` **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. :param `origString`: :type `origString`: string :param `domain`: :type `domain`: string :rtype: `string` .. versionadded:: 3.0 .. note:: Domains are searched in the last to first order, i.e. catalogs added later override those added before. :html:`

` **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. :param `origString`: The singular form of the string to be converted. :type `origString`: string :param `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.) :param `domain`: 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. :type `domain`: string :rtype: `string` `wx.GetTranslation` function and `wx._` macro. This function is thread-safe. .. versionadded:: 3.0 .. note:: Domains are searched in the last to first order, i.e. catalogs added later override those added before. :html:`

` .. method:: 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. :param `domain`: :type `domain`: string :rtype: `bool` .. seealso:: :meth:`AddCatalog` .. staticmethod:: Set(t) Sets current translations object. Deletes previous translation object and takes ownership of `t`. :param `t`: :type `t`: wx.Translations .. method:: SetLanguage(self, *args, **kw) |overload| Overloaded Implementations: :html:`

` **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. :param `lang`: :type `lang`: wx.Language :html:`

` **SetLanguage** `(self, lang)` Sets translations language to use. Empty `lang` string has the same meaning as ``wx.LANGUAGE_DEFAULT`` in :meth:`SetLanguage` : best suitable translation, given user's preference and available translations, will be used. :param `lang`: :type `lang`: string :html:`

` .. method:: SetLoader(self, loader) Changes loader use to read catalogs to a non-default one. Deletes previous loader and takes ownership of `loader`. :param `loader`: :type `loader`: wx.TranslationsLoader .. seealso:: :ref:`wx.TranslationsLoader`, :ref:`wx.FileTranslationsLoader`, `ResourceTranslationsLoader`