.. wxPython Phoenix documentation
This file was generated by Phoenix's sphinx generator and associated
tools, do not edit by hand.
Copyright: (c) 2011-2018 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
<div id="toggleBlock" onclick="return toggleVisibility(this)" class="closed" style="cursor:pointer;">
<img id="toggleBlock-trigger" src="_static/images/closed.png"/>
Inheritance diagram for class <strong>Translations</strong>:
</div>
<div id="toggleBlock-summary" style="display:block;"></div>
<div id="toggleBlock-content" style="display:none;">
<p class="graphviz">
<center><img src="_static/images/inheritance/wx.Translations_inheritance.png" alt="Inheritance diagram of Translations" usemap="#dummy" class="inheritance"/></center>
<script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
<map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.Translations.html" title="This class allows getting translations for strings." alt="" coords="5,5,132,35"/> </map>
</p>
</div>
|
|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, *args, **kw)
|overload| Overloaded Implementations:
:html:`<hr class="overloadsep" /><br />`
**AddCatalog** `(self, domain)`
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.
In this overload, ``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 <writing non-english applications>`.
:param `domain`:
:type `domain`: string
: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).
:html:`<hr class="overloadsep" /><br />`
**AddCatalog** `(self, domain, msgIdLanguage)`
Same as :meth:`AddCatalog` , but takes an additional argument, `msgIdLanguage`.
: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).
:html:`<hr class="overloadsep" /><br />`
.. 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+, OS X) 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:`<hr class="overloadsep" /><br />`
**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:`<hr class="overloadsep" /><br />`
**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:`<hr class="overloadsep" /><br />`
.. method:: GetHeaderValue(self, header, domain="")
Returns the header value for header `header`.
The search for `header` is case sensitive. If an `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:`<hr class="overloadsep" /><br />`
**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:`<hr class="overloadsep" /><br />`
**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:`<hr class="overloadsep" /><br />`
.. 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:`<hr class="overloadsep" /><br />`
**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:`<hr class="overloadsep" /><br />`
**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:`<hr class="overloadsep" /><br />`
.. 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`