.. 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

   <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="wx.Translations" alt="" coords="5,5,128,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, 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 <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(), :ref:`wx.GetTranslation`  and the :ref:`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(), :ref:`wx.GetTranslation`  and the :ref:`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(), :ref:`wx.GetTranslation`  and the :ref:`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(), :ref:`wx.GetTranslation`  and the :ref:`wx._`  macro).  
      :type `msgIdLanguage`: string
      
      
      
      
      
      
      
      
      :rtype: `string`
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






   .. method:: GetHeaderValue(self, header, domain=EmptyString)

      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:`<hr class="overloadsep" /><br />`

      
      **GetTranslatedString** `(self, origString, domain=EmptyString)`
      
      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=EmptyString)`
      
      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`
      
      
      
      :ref:`wx.GetTranslation`  function and :ref:`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`, :ref:`ResourceTranslationsLoader`    







