.. 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.AddAvailableCatalog` Add a catalog for use with the current locale. :meth:`~wx.Translations.AddCatalog` Add a catalog for use with the current locale or fall back to the original messages language. :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.GetBestAvailableTranslation` Returns the best available translation for the required language. :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() -> None This class allows getting translations for strings. .. method:: __init__(self) Constructor. :rtype: `None` .. method:: AddAvailableCatalog(self, domain : str, msgIdLanguage: Language=LANGUAGE_ENGLISH_US) Add a catalog for use with the current locale. By default, the catalog 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. :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, usually because it wasn't found. Note that unlike :meth:`AddCatalog` this function returns ``False`` even if the language of the original strings (usually English) can be used directly, i.e. its return value only indicates that there are no catalogs available for the selected or system-default languages, but is not necessarily an error if no translations are needed in the first place. .. versionadded:: 4.2/wxWidgets-3.2.3 (the msgIdLanguage argument since 3.2.6) .. method:: AddCatalog(self, domain : str, msgIdLanguage: Language=LANGUAGE_ENGLISH_US) Add a catalog for use with the current locale or fall back to the original messages language. This function behaves like :meth:`AddAvailableCatalog` but also checks if the strings used in the program, written in `msgIdLanguage`, can be used without any translations on the current system and also returns ``True`` in this case, unlike :meth:`AddAvailableCatalog` . 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 or loading it is unnecessary because the original messages can be used directly, ``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:`AddAvailableCatalog` .. 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 : str) 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[str]` .. note:: The returned list does not include messages ``ID`` language, i.e. the language (typically English) included in the source code. In the use case described above, that language needs to be added manually. .. seealso:: :meth:`GetBestTranslation` .. method:: GetBestAvailableTranslation(self, domain : str) Returns the best available translation for the required language. For ``wx.LANGUAGE_DEFAULT``, this function returns the available translation best matching one of `UILocale.GetPreferredUILanguages().` Otherwise it simply returns the language set with :meth:`SetLanguage` if it's available or empty string otherwise. :param `domain`: :type `domain`: string :rtype: `str` .. versionadded:: 4.2/wxWidgets-3.2.3 .. warning:: This function does not consider messages ``ID`` language (typically English) and can return inappropriate language if it is anywhere in user's preferred languages list. Use :meth:`GetBestTranslation` instead unless you have very specific needs. .. method:: GetBestTranslation(self, *args, **kw) |overload| **Overloaded Implementations:** :html:`

` **GetBestTranslation** `(self, domain : str, msgIdLanguage : Language)` 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. Please note that that this function may return the language corresponding to `msgIdLanguage` if this language is considered to be acceptable, i.e. is part of `UILocale.GetPreferredUILanguages(),` indicating that it is fine not to use translations at all on this system. If this is undesirable, :meth:`GetBestAvailableTranslation` should be used which doesn't consider the messages ``ID`` language as being available. :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: `str` :returns: Language code if a suitable match was found, empty string otherwise. .. versionadded:: 2.9.5 :html:`

` **GetBestTranslation** `(self, domain : str, msgIdLanguage: str="en")` 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`: string :rtype: `str` :returns: Language code if a suitable match was found, empty string otherwise. .. versionadded:: 2.9.5 :html:`

` .. method:: GetHeaderValue(self, header : str, domain: str='') 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: `str` .. method:: GetTranslatedString(self, *args, **kw) |overload| **Overloaded Implementations:** :html:`

` **GetTranslatedString** `(self, origString : str, domain: str='')` 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: `str` .. 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 : str, n : int, domain: str='')` 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: `str` `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 : str) 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:`AddAvailableCatalog` .. staticmethod:: Set(t : Translations) Sets current translations object. Deletes previous translation object and takes ownership of `t`. :param `t`: :type `t`: wx.Translations :rtype: `None` .. method:: SetLanguage(self, *args, **kw) |overload| **Overloaded Implementations:** :html:`

` **SetLanguage** `(self, lang : Language)` 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 :rtype: `None` :html:`

` **SetLanguage** `(self, lang : str)` 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 :rtype: `None` :html:`

` .. method:: SetLoader(self, loader : TranslationsLoader) 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 :rtype: `None` .. seealso:: :ref:`wx.TranslationsLoader`, :ref:`wx.FileTranslationsLoader`, `ResourceTranslationsLoader`