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

==========================================================================================================================================
|phoenix_title|  **wx.Locale**
==========================================================================================================================================

:ref:`wx.Locale`  class encapsulates all language-dependent settings and is a generalization of the C locale concept.          

In wxWidgets this class manages current locale. It also initializes and activates :ref:`wx.Translations`  object that manages message catalogs. 

For a list of the supported languages, please see :ref:`wx.Language`  enum values. These constants may be used to specify the language in :meth:`wx.Locale.Init`   and are returned by :meth:`wx.Locale.GetSystemLanguage` . 





|

|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>Locale</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.Locale_inheritance.png" alt="Inheritance diagram of Locale" usemap="#dummy" class="inheritance"/></center>
   </div>
   <script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.Locale.html" title="wx.Locale" alt="" coords="4,5,85,35"/> </map> 
   </p>

|


|method_summary| Methods Summary
================================

================================================================================ ================================================================================
:meth:`~wx.Locale.__init__`                                                      This is the default constructor and it does nothing to initialize the object: :meth:`~Locale.Init`   must be used to do that.
:meth:`~wx.Locale.AddCatalog`                                                    Calls :meth:`wx.Translations.AddCatalog` .
:meth:`~wx.Locale.AddCatalogLookupPathPrefix`                                    Calls :meth:`wx.FileTranslationsLoader.AddCatalogLookupPathPrefix` .
:meth:`~wx.Locale.AddLanguage`                                                   Adds custom, user-defined language to the database of known languages.
:meth:`~wx.Locale.FindLanguageInfo`                                              This function may be used to find the language description structure for the given locale, specified either as a two letter ``ISO`` language code (for example, "pt"), a language code followed by the country code ("pt_BR") or a full, human readable, language description ("Portuguese-Brazil").
:meth:`~wx.Locale.GetCanonicalName`                                              Returns the canonical form of current locale name.
:meth:`~wx.Locale.GetHeaderValue`                                                Calls :meth:`wx.Translations.GetHeaderValue` .
:meth:`~wx.Locale.GetInfo`                                                       Get the values of the given locale-dependent datum.
:meth:`~wx.Locale.GetLanguage`                                                   Returns the :ref:`wx.Language`  constant of current language.
:meth:`~wx.Locale.GetLanguageCanonicalName`                                      Returns canonical name (see :meth:`~Locale.GetCanonicalName` ) of the given language or empty string if this language is unknown.
:meth:`~wx.Locale.GetLanguageInfo`                                               Returns a pointer to :ref:`wx.LanguageInfo`  structure containing information about the given language or ``None`` if this language is unknown.
:meth:`~wx.Locale.GetLanguageName`                                               Returns English name of the given language or empty string if this language is unknown.
:meth:`~wx.Locale.GetLocale`                                                     Returns the locale name as passed to the constructor or :meth:`~Locale.Init` .
:meth:`~wx.Locale.GetName`                                                       Returns the current short name for the locale (as given to the constructor or the :meth:`~Locale.Init`   function).
:meth:`~wx.Locale.GetString`                                                     Calls :ref:`wx.GetTranslation`.
:meth:`~wx.Locale.GetSysName`                                                    Returns current platform-specific locale name as passed to setlocale().
:meth:`~wx.Locale.GetSystemEncoding`                                             Tries to detect the user's default font encoding.
:meth:`~wx.Locale.GetSystemEncodingName`                                         Tries to detect the name of the user's default font encoding.
:meth:`~wx.Locale.GetSystemLanguage`                                             Tries to detect the user's default locale setting.
:meth:`~wx.Locale.Init`                                                          Initializes the :ref:`wx.Locale`  instance.
:meth:`~wx.Locale.IsAvailable`                                                   Check whether the operating system and/or C run time environment supports this locale.
:meth:`~wx.Locale.IsLoaded`                                                      Calls :meth:`wx.Translations.IsLoaded` .
:meth:`~wx.Locale.IsOk`                                                          Returns ``True`` if the locale could be set successfully.
:meth:`~wx.Locale.__bool__`                                                      
:meth:`~wx.Locale.__nonzero__`                                                   
================================================================================ ================================================================================


|


|property_summary| Properties Summary
=====================================

================================================================================ ================================================================================
:attr:`~wx.Locale.CanonicalName`                                                 See :meth:`~wx.Locale.GetCanonicalName`
:attr:`~wx.Locale.Language`                                                      See :meth:`~wx.Locale.GetLanguage`
:attr:`~wx.Locale.Locale`                                                        See :meth:`~wx.Locale.GetLocale`
:attr:`~wx.Locale.Name`                                                          See :meth:`~wx.Locale.GetName`
:attr:`~wx.Locale.SysName`                                                       See :meth:`~wx.Locale.GetSysName`
================================================================================ ================================================================================


|


|api| Class API
===============


.. class:: wx.Locale(object)

   **Possible constructors**::

       Locale()
       
       Locale(language, flags=LOCALE_LOAD_DEFAULT)
       
       Locale(name, shortName=EmptyString, locale=EmptyString,
              bLoadDefault=True)
       
   
   Locale class encapsulates all language-dependent settings and is a
   generalization of the C locale concept.



   .. method:: __init__(self, *args, **kw)



      |overload| Overloaded Implementations:

      **~~~**

      
      **__init__** `(self)`
      
      This is the default constructor and it does nothing to initialize the object: :meth:`Init`   must be used to do that.                   
      
      
      
      
      **~~~**

      
      **__init__** `(self, language, flags=LOCALE_LOAD_DEFAULT)`
      
      See :meth:`Init`   for parameters description.                  
      
      
      :param `language`: 
      :type `language`: int
      :param `flags`: 
      :type `flags`: int
      
      
      
      
      
      
      **~~~**

      
      **__init__** `(self, name, shortName=EmptyString, locale=EmptyString, bLoadDefault=True)`
      
      See :meth:`Init`   for parameters description.                  
      
      The call of this function has several global side effects which you should understand: first of all, the application locale is changed - note that this will affect many of standard C library functions such as printf() or strftime(). Second, this :ref:`wx.Locale`  object becomes the new current global locale for the application and so all subsequent calls to :ref:`wx.GetTranslation`  will try to translate the messages using the message catalogs for this locale.                  
      
      
      :param `name`: 
      :type `name`: string
      :param `shortName`: 
      :type `shortName`: string
      :param `locale`: 
      :type `locale`: string
      :param `bLoadDefault`: 
      :type `bLoadDefault`: bool
      
      
      
      
      
      
      **~~~**






   .. method:: AddCatalog(self, *args, **kw)

      Calls :meth:`wx.Translations.AddCatalog` .                   


      |overload| Overloaded Implementations:

      **~~~**

      
      **AddCatalog** `(self, domain)`
      
      
      
      
      :param `domain`: 
      :type `domain`: string
      
      
      
      
      :rtype: `bool`
      
      
      
      
      
      
      
      **~~~**

      
      **AddCatalog** `(self, domain, msgIdLanguage)`
      
      
      
      
      :param `domain`: 
      :type `domain`: string
      :param `msgIdLanguage`: 
      :type `msgIdLanguage`: wx.Language
      
      
      
      
      :rtype: `bool`
      
      
      
      
      
      
      
      **~~~**

      
      **AddCatalog** `(self, domain, msgIdLanguage, msgIdCharset)`
      
      
      
      
      :param `domain`: 
      :type `domain`: string
      :param `msgIdLanguage`: 
      :type `msgIdLanguage`: wx.Language
      :param `msgIdCharset`: 
      :type `msgIdCharset`: string
      
      
      
      
      :rtype: `bool`
      
      
      
      
      
      
      
      **~~~**






   .. staticmethod:: AddCatalogLookupPathPrefix(prefix)

      Calls :meth:`wx.FileTranslationsLoader.AddCatalogLookupPathPrefix` .                  


      :param `prefix`: 
      :type `prefix`: string







   .. staticmethod:: AddLanguage(info)

      Adds custom, user-defined language to the database of known languages.                  

      This database is used in conjunction with the first form of :meth:`Init` .                  


      :param `info`: 
      :type `info`: wx.LanguageInfo







   .. staticmethod:: FindLanguageInfo(locale)

      This function may be used to find the language description structure for the given locale, specified either as a two letter ``ISO`` language code (for example, "pt"), a language code followed by the country code ("pt_BR") or a full, human readable, language description ("Portuguese-Brazil").                  

      Returns the information for the given language or ``None`` if this language is unknown. Note that even if the returned pointer is valid, the caller should `not`  delete it. 

                


      :param `locale`: 
      :type `locale`: string




      :rtype: :ref:`wx.LanguageInfo`







      .. seealso:: :meth:`GetLanguageInfo`     








   .. method:: GetCanonicalName(self)

      Returns the canonical form of current locale name.                  

      Canonical form is the one that is used on ``UNIX`` systems: it is a two- or five-letter string in xx or xx_YY format, where xx is ``ISO`` 639 code of language and ``YY`` is ``ISO`` 3166 code of the country. Examples are "en", "en_GB", "en_US" or "fr_FR". This form is internally used when looking up message catalogs. Compare :meth:`GetSysName` .                  

      :rtype: `string`








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

      Calls :meth:`wx.Translations.GetHeaderValue` .                  


      :param `header`: 
      :type `header`: string
      :param `domain`: 
      :type `domain`: string




      :rtype: `string`








   .. staticmethod:: GetInfo(index, cat=LOCALE_CAT_DEFAULT)

      Get the values of the given locale-dependent datum.                  

      This function returns the value of the locale-specific option specified by the given `index`. 




      :param `index`: One of the elements of LocaleInfo enum.   
      :type `index`: wx.LocaleInfo
      :param `cat`: The category to use with the given index or ``wx.LOCALE_CAT_DEFAULT`` if the index can only apply to a single category.   
      :type `cat`: wx.LocaleCategory








      :rtype: `string`



                  



      :returns: 

         The option value or empty string if the function failed.   








   .. method:: GetLanguage(self)

      Returns the :ref:`wx.Language`  constant of current language.                  

      Note that you can call this function only if you used the form of :meth:`Init`   that takes :ref:`wx.Language`  argument.                  

      :rtype: `int`








   .. staticmethod:: GetLanguageCanonicalName(lang)

      Returns canonical name (see :meth:`GetCanonicalName` ) of the given language or empty string if this language is unknown.                  

      See :meth:`GetLanguageInfo`   for a remark about special meaning of  ``LANGUAGE_DEFAULT`` . 

                


      :param `lang`: 
      :type `lang`: int




      :rtype: `string`







      .. versionadded:: 2.9.1 
     








   .. staticmethod:: GetLanguageInfo(lang)

      Returns a pointer to :ref:`wx.LanguageInfo`  structure containing information about the given language or ``None`` if this language is unknown.                  

      Note that even if the returned pointer is valid, the caller should `not`  delete it. 

      See :meth:`AddLanguage`   for the :ref:`wx.LanguageInfo`  description. As with :meth:`Init` ,  ``LANGUAGE_DEFAULT``   has the special meaning if passed as an argument to this function and in this case the result of  :meth:`GetSystemLanguage`   is used.                  


      :param `lang`: 
      :type `lang`: int




      :rtype: :ref:`wx.LanguageInfo`








   .. staticmethod:: GetLanguageName(lang)

      Returns English name of the given language or empty string if this language is unknown.                  

      See :meth:`GetLanguageInfo`   for a remark about special meaning of  ``LANGUAGE_DEFAULT`` .                   


      :param `lang`: 
      :type `lang`: int




      :rtype: `string`








   .. method:: GetLocale(self)

      Returns the locale name as passed to the constructor or :meth:`Init` .                  

      This is a full, human-readable name, e.g. "English" or "French".                  

      :rtype: `string`








   .. method:: GetName(self)

      Returns the current short name for the locale (as given to the constructor or the :meth:`Init`   function).                  

      :rtype: `string`








   .. method:: GetString(self, *args, **kw)

      Calls :ref:`wx.GetTranslation`.                   


      |overload| Overloaded Implementations:

      **~~~**

      
      **GetString** `(self, origString, domain=EmptyString)`
      
      
      
      
      :param `origString`: 
      :type `origString`: string
      :param `domain`: 
      :type `domain`: string
      
      
      
      
      :rtype: `string`
      
      
      
      
      
      
      
      **~~~**

      
      **GetString** `(self, origString, origString2, n, domain=EmptyString)`
      
      
      
      
      :param `origString`: 
      :type `origString`: string
      :param `origString2`: 
      :type `origString2`: string
      :param `n`: 
      :param `domain`: 
      :type `domain`: string
      
      
      
      
      :rtype: `string`
      
      
      
      
      
      
      
      **~~~**






   .. method:: GetSysName(self)

      Returns current platform-specific locale name as passed to setlocale().                  

      Compare :meth:`GetCanonicalName` .                  

      :rtype: `string`








   .. staticmethod:: GetSystemEncoding()

      Tries to detect the user's default font encoding.                  

      Returns :ref:`wx.FontEncoding`  value or  ``FONTENCODING_SYSTEM``   if it couldn't be determined.                   

      :rtype: :ref:`wx.FontEncoding`








   .. staticmethod:: GetSystemEncodingName()

      Tries to detect the name of the user's default font encoding.                  

      This string isn't particularly useful for the application as its form is platform-dependent and so you should probably use :meth:`GetSystemEncoding`   instead. 

      Returns a user-readable string value or an empty string if it couldn't be determined.                  

      :rtype: `string`








   .. staticmethod:: GetSystemLanguage()

      Tries to detect the user's default locale setting.                  

      Returns the :ref:`wx.Language`  value or  ``LANGUAGE_UNKNOWN``   if the language-guessing algorithm failed. 

                

      :rtype: `int`







      .. note:: 

         This function works with `locales`  and returns the user's default locale. This may be, and usually is, the same as their preferred UI language, but it's not the same thing. Use Translation to obtain `language`  information.  







      .. seealso:: :meth:`wx.Translations.GetBestTranslation` .   








   .. method:: Init(self, *args, **kw)



      |overload| Overloaded Implementations:

      **~~~**

      
      **Init** `(self, language=LANGUAGE_DEFAULT, flags=LOCALE_LOAD_DEFAULT)`
      
      Initializes the :ref:`wx.Locale`  instance.                  
      
      The call of this function has several global side effects which you should understand: first of all, the application locale is changed - note that this will affect many of standard C library functions such as printf() or strftime(). Second, this :ref:`wx.Locale`  object becomes the new current global locale for the application and so all subsequent calls to :ref:`wx.GetTranslation`  will try to translate the messages using the message catalogs for this locale. 
      
      
      
      
      :param `language`: :ref:`wx.Language`  identifier of the locale.  ``LANGUAGE_DEFAULT``   has special meaning  :ref:`wx.Locale`  will use system's default language (see :meth:`GetSystemLanguage` ).   
      :type `language`: int
      :param `flags`: Combination of the following:
      
       - ``LOCALE_LOAD_DEFAULT``: Load the message catalog for the given locale containing the translations of standard wxWidgets messages automatically. 
       - ``LOCALE_DONT_LOAD_DEFAULT``: Negation of ``LOCALE_LOAD_DEFAULT``. 
      
       
      
      :type `flags`: int
      
      
      
      
      
      
      
      
      :rtype: `bool`
      
      
      
                        
      
      
      
      :returns: 
      
         ``True`` on success or ``False`` if the given locale couldn't be set.   
      
      
      
      
      
      
      
      **~~~**

      
      **Init** `(self, name, shortName=EmptyString, locale=EmptyString, bLoadDefault=True)`
      
      
      
      
      
      
      
      
      :param `name`: The name of the locale. Only used in diagnostic messages.   
      :type `name`: string
      :param `shortName`: The standard 2 letter locale abbreviation; it is used as the directory prefix when looking for the message catalog files.   
      :type `shortName`: string
      :param `locale`: The parameter for the call to setlocale(). Note that it is platform-specific.   
      :type `locale`: string
      :param `bLoadDefault`: May be set to ``False`` to prevent loading of the message catalog for the given locale containing the translations of standard wxWidgets messages. This parameter would be rarely used in normal circumstances.   
      :type `bLoadDefault`: bool
      
      
      
      
      
      
      
      
      
      
      
      
      :rtype: `bool`
      
      
      
                        
      
      
      
      .. wxdeprecated:: 
         This form is deprecated, use the other one unless you know what you are doing.   
      
      
      
      
      
      
      
      **~~~**






   .. staticmethod:: IsAvailable(lang)

      Check whether the operating system and/or C run time environment supports this locale.                  

      For example in Windows 2000 and Windows XP, support for many locales is not installed by default. Returns ``True`` if the locale is supported. 

      The argument `lang`  is the :ref:`wx.Language`  identifier. To obtain this for a given a two letter ``ISO`` language code, use :meth:`FindLanguageInfo`   to obtain its :ref:`wx.LanguageInfo`  structure. See :meth:`AddLanguage`   for the :ref:`wx.LanguageInfo`  description. 

                


      :param `lang`: 
      :type `lang`: int




      :rtype: `bool`







      .. versionadded:: 2.7.1.
      








   .. method:: IsLoaded(self, domain)

      Calls :meth:`wx.Translations.IsLoaded` .                  


      :param `domain`: 
      :type `domain`: string




      :rtype: `bool`








   .. method:: IsOk(self)

      Returns ``True`` if the locale could be set successfully.                  

      :rtype: `bool`








   .. method:: __bool__(self)



      :rtype: `int`








   .. method:: __nonzero__(self)



      :rtype: `int`








   .. attribute:: CanonicalName

      See :meth:`~wx.Locale.GetCanonicalName`


   .. attribute:: Language

      See :meth:`~wx.Locale.GetLanguage`


   .. attribute:: Locale

      See :meth:`~wx.Locale.GetLocale`


   .. attribute:: Name

      See :meth:`~wx.Locale.GetName`


   .. attribute:: SysName

      See :meth:`~wx.Locale.GetSysName`