.. wxPython Phoenix documentation This file was generated by Phoenix's sphinx generator and associated tools, do not edit by hand. Copyright: (c) 2011-2017 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
Inheritance diagram for class Locale:

| |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 `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.__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="", locale="", 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="", locale="", 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 `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="") 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 `wx.GetTranslation` . |overload| Overloaded Implementations: **~~~** **GetString** `(self, origString, domain="")` :param `origString`: :type `origString`: string :param `domain`: :type `domain`: string :rtype: `string` **~~~** **GetString** `(self, origString, origString2, n, domain="")` :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 `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="", locale="", 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` .. deprecated:: 4.0.1 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:: __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`