.. include:: headings.inc .. _Locale: ========================================================================================================================================== |phoenix_title| **Locale** ========================================================================================================================================== :ref:`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:`Translations` object that manages message catalogs. For a list of the supported languages, please see :meth:`~Locale.Language` enum values. These constants may be used to specify the language in :meth:`Locale.Init` and are returned by :meth:`Locale.GetSystemLanguage` . If you need to translate a lot of strings, then adding gettext( ) around each one is a long task ( that is why :func:`_` was introduced ), so just choose a shorter name for gettext: .. seealso:: :ref:`Internationalization `, `XLocale`, :ref:`Translations` | |class_hierarchy| Inheritance Diagram ===================================== Inheritance diagram for class **Locale** .. raw:: html

Inheritance diagram of Locale

| |method_summary| Methods Summary ================================ ================================================================================ ================================================================================ :meth:`~Locale.__init__` This is the default constructor and it does nothing to initialize the object: :meth:`Init` must be used to do that. :meth:`~Locale.AddCatalog` Calls :meth:`Translations.AddCatalog` . :meth:`~Locale.AddCatalogLookupPathPrefix` Calls :meth:`FileTranslationsLoader.AddCatalogLookupPathPrefix` . :meth:`~Locale.AddLanguage` Adds custom, user-defined language to the database of known languages. :meth:`~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:`~Locale.GetCanonicalName` Returns the canonical form of current locale name. :meth:`~Locale.GetHeaderValue` Calls :meth:`Translations.GetHeaderValue` . :meth:`~Locale.GetInfo` Get the values of the given locale-dependent datum. :meth:`~Locale.GetLanguage` Returns the :ref:`Language` constant of current language. :meth:`~Locale.GetLanguageCanonicalName` Returns canonical name (see :meth:`GetCanonicalName` ) of the given language or empty string if this language is unknown. :meth:`~Locale.GetLanguageInfo` Returns a pointer to :ref:`LanguageInfo` structure containing information about the given language or ``None`` if this language is unknown. :meth:`~Locale.GetLanguageName` Returns English name of the given language or empty string if this language is unknown. :meth:`~Locale.GetLocale` Returns the locale name as passed to the constructor or :meth:`Init` . :meth:`~Locale.GetName` Returns the current short name for the locale (as given to the constructor or the :meth:`Init` function). :meth:`~Locale.GetString` Calls :meth:`Translations.GetString` . :meth:`~Locale.GetSysName` Returns current platform-specific locale name as passed to setlocale(). :meth:`~Locale.GetSystemEncoding` Tries to detect the user's default font encoding. :meth:`~Locale.GetSystemEncodingName` Tries to detect the name of the user's default font encoding. :meth:`~Locale.GetSystemLanguage` Tries to detect the user's default language setting. :meth:`~Locale.Init` Initializes the :ref:`Locale` instance. :meth:`~Locale.IsAvailable` Check whether the operating system and/or C run time environment supports this locale. :meth:`~Locale.IsLoaded` Calls :meth:`Translations.IsLoaded` . :meth:`~Locale.IsOk` Returns ``True`` if the locale could be set successfully. :meth:`~Locale.__nonzero__` ================================================================================ ================================================================================ | |property_summary| Properties Summary ===================================== ================================================================================ ================================================================================ :attr:`~Locale.CanonicalName` See :meth:`~Locale.GetCanonicalName` :attr:`~Locale.Language` See :meth:`~Locale.GetLanguage` :attr:`~Locale.Locale` See :meth:`~Locale.GetLocale` :attr:`~Locale.Name` See :meth:`~Locale.GetName` :attr:`~Locale.SysName` See :meth:`~Locale.GetSysName` ================================================================================ ================================================================================ | |api| Class API =============== .. class:: Locale(object) Locale class encapsulates all language-dependent settings and is a generalization of the C locale concept. **Possible constructors**:: Locale() Locale(language, flags=LOCALE_LOAD_DEFAULT) Locale(name, shortName='', locale='', bLoadDefault=True) .. 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:`Locale` object becomes the new current global locale for the application and so all subsequent calls to :func:`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:`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`: Language :rtype: `bool` **~~~** **AddCatalog** `(self, domain, msgIdLanguage, msgIdCharset)` :param `domain`: :type `domain`: string :param `msgIdLanguage`: :type `msgIdLanguage`: Language :param `msgIdCharset`: :type `msgIdCharset`: string :rtype: `bool` **~~~** .. staticmethod:: AddCatalogLookupPathPrefix(prefix) Calls :meth:`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`: 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:`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:`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`: LocaleInfo :param `cat`: The category to use with the given index or ``LOCALE_CAT_DEFAULT`` if the index can only apply to a single category. :type `cat`: LocaleCategory :rtype: `string` :returns: The option value or empty string if the function failed. .. method:: GetLanguage(self) Returns the :ref:`Language` constant of current language. Note that you can call this function only if you used the form of :meth:`Init` that takes :ref:`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:`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:`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:`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 :meth:`Translations.GetString` . |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:`FontEncoding` value or ``FONTENCODING_SYSTEM`` if it couldn't be determined. :rtype: :ref:`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 language setting. Returns the :ref:`Language` value or ``LANGUAGE_UNKNOWN`` if the language-guessing algorithm failed. :rtype: `int` .. method:: Init(self, *args, **kw) |overload| **Overloaded Implementations**: **~~~** **Init** `(self, language=LANGUAGE_DEFAULT, flags=LOCALE_LOAD_DEFAULT)` Initializes the :ref:`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:`Locale` object becomes the new current global locale for the application and so all subsequent calls to :func:`GetTranslation` will try to translate the messages using the message catalogs for this locale. :param `language`: :ref:`Language` identifier of the locale. ``LANGUAGE_DEFAULT`` has special meaning -- :ref:`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`: :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 The standard 2 letter locale abbreviation; it is used as the directory prefix when looking for the message catalog files. :rtype: `bool` .. deprecated:: 2.9.4 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:`Language` identifier. To obtain this for a given a two letter ``ISO`` language code, use :meth:`FindLanguageInfo` to obtain its :ref:`LanguageInfo` structure. See :meth:`AddLanguage` for the :ref:`LanguageInfo` description. :param `lang`: :type `lang`: int :rtype: `bool` .. versionadded:: 2.7.1. .. method:: IsLoaded(self, domain) Calls :meth:`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:`~Locale.GetCanonicalName` .. attribute:: Language See :meth:`~Locale.GetLanguage` .. attribute:: Locale See :meth:`~Locale.GetLocale` .. attribute:: Name See :meth:`~Locale.GetName` .. attribute:: SysName See :meth:`~Locale.GetSysName`