********* wx.Locale ********* Inheritance diagram for `wx.Locale`: | .. inheritance-diagram:: wx.Locale | Description =========== `wx.Locale` class encapsulates all language-dependent settings and is a generalization of the C locale concept. In wxWidgets this class manages message catalogs which contain the translations of the strings used to the current language. Known Subclasses ^^^^^^^^^^^^^^^^ `wx.PyLocale `_ Methods Summary ^^^^^^^^^^^^^^^ * `__init__ <#__init__>`_ * `AddCatalog <#AddCatalog>`_ * `AddCatalogLookupPathPrefix <#AddCatalogLookupPathPrefix>`_ * `AddLanguage <#AddLanguage>`_ * `FindLanguageInfo <#FindLanguageInfo>`_ * `GetCanonicalName <#GetCanonicalName>`_ * `GetLanguage <#GetLanguage>`_ * `GetLanguageInfo <#GetLanguageInfo>`_ * `GetLanguageName <#GetLanguageName>`_ * `GetLocale <#GetLocale>`_ * `GetName <#GetName>`_ * `GetString <#GetString>`_ * `GetSysName <#GetSysName>`_ * `GetSystemEncoding <#GetSystemEncoding>`_ * `GetSystemEncodingName <#GetSystemEncodingName>`_ * `GetSystemLanguage <#GetSystemLanguage>`_ * `Init <#Init>`_ * `Init1 <#Init1>`_ * `Init2 <#Init2>`_ * `IsAvailable <#IsAvailable>`_ * `IsLoaded <#IsLoaded>`_ * `IsOk <#IsOk>`_ Properties Summary ^^^^^^^^^^^^^^^^^^ * `CanonicalName <#CanonicalName>`_ * `Language <#Language>`_ * `Locale <#Locale>`_ * `Name <#Name>`_ * `String <#String>`_ * `SysName <#SysName>`_ Class API ========= Methods ^^^^^^^ .. method:: __init__(language=-1, flags=wx.LOCALE_LOAD_DEFAULT|wx.LOCALE_CONV_ENCODING) Constructor. **Parameters:** * `language` (int) * `flags` (int) | **Returns:** `wx.Locale `_ -------- .. method:: AddCatalog(szDomain) Add a catalog for use with the current locale: it is searched for in standard places (current directory first, then the system one), but you may also prepend additional directories to the search path with `AddCatalogLookupPathPrefix <#AddCatalogLookupPathPrefix>`_. All loaded catalogs will be used for message lookup by `GetString <#GetString>`_ for the current locale. 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). By default *msgid* strings are assumed to be in English and written only using 7-bit ASCII characters. **Parameters:** * `szDomain` (string) | **Returns:** `bool` -------- .. method:: AddCatalogLookupPathPrefix(prefix) Add a prefix to the catalog lookup path: the message catalog files will be looked up under ``prefix//LC_MESSAGES``, ``prefix/``, and ``prefix`` (in this order). This only applies to subsequent invocations of `AddCatalog()`. **Parameters:** * `prefix` (string) -------- .. method:: AddLanguage(info) Adds custom, user-defined language to the database of known languages. **Parameters:** * `info` (`wx.LanguageInfo`) -------- .. method:: 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. **Parameters:** * `locale` (string) | **Returns:** `wx.LanguageInfo` .. note:: Note that even if the returned pointer is valid, the caller should *not* delete it. .. seealso:: `GetLanguageInfo <#GetLanguageInfo>`_ -------- .. method:: GetCanonicalName() 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. | **Returns:** `string` .. seealso:: `GetSysName <#GetSysName>`_. -------- .. method:: GetLanguage() Returns `wx.Language` constant of current language. | **Returns:** `int` -------- .. method:: GetLanguageInfo(lang) Returns a pointer to `wx.LanguageInfo` structure containing information about the given language or ``None`` if this language is unknown. **Parameters:** * `lang` (int) | **Returns:** `wx.LanguageInfo` .. note:: Note that even if the returned pointer is valid, the caller should *not* delete it. -------- .. method:: GetLanguageName(lang) Returns English name of the given language or empty string if this language is unknown. **Parameters:** * `lang` (int) | **Returns:** `string` -------- .. method:: GetLocale() Returns the locale name as passed to the constructor. This is full, human-readable name, e.g. "English" or "French". | **Returns:** `string` -------- .. method:: GetName() Returns the current short name for the locale (as given to the constructor or the `Init() <#Init>`_ function). | **Returns:** `string` -------- .. method:: GetString(szOrigString, szDomain=None) Retrieves the translation for a string in all loaded domains unless the `szDomain` parameter is specified (and then only this catalog/domain is searched). Returns original string if translation is not available (in this case an error message is generated the first time a string is not found; use `wx.LogNull `_ to suppress it). This method is called by the `wx.GetTranslation <../wxFunctions.html#GetTranslation>`_ function and ``_`` macro. **Parameters:** * `szOrigString` (string) * `szDomain` (string) | **Returns:** `string` .. note:: Domains are searched in the last to first order, i.e. catalogs added later override those added before. -------- .. method:: GetSysName() Returns current platform-specific locale name as passed to setlocale(). | **Returns:** `string` .. seealso:: `GetCanonicalName <#GetCanonicalName>`_ -------- .. method:: GetSystemEncoding() Tries to detect the user's default font encoding. Returns `wx.FontEncoding` value or ``wx.FONTENCODING_SYSTEM`` if it couldn't be determined. | **Returns:** `int` -------- .. method:: 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 `GetSystemEncoding <#GetSystemEncoding>`_ instead. Returns a user-readable string value or an empty string if it couldn't be determined. | **Returns:** `string` -------- .. method:: GetSystemLanguage() Tries to detect the user's default language setting. Returns `wx.Language` value or ``wx.LANGUAGE_UNKNOWN`` if the language-guessing algorithm failed. | **Returns:** `int` -------- .. method:: Init(language=wx.LANGUAGE_DEFAULT, flags=wx.LOCALE_LOAD_DEFAULT|wx.LOCALE_CONV_ENCODING) | **Parameters:** * `language` (int): identifier of the locale. ``wx.LANGUAGE_DEFAULT`` has special meaning -- `wx.Locale` will use system's default language (see `GetSystemLanguage <#GetSystemLanguage>`_). * `flags` (int): Combination of the following: =================================== ======================================= Locale Flags Description =================================== ======================================= ``wx.LOCALE_LOAD_DEFAULT`` Load the message catalog for the given locale containing the translations of standard wxWidgets messages automatically. ``wx.LOCALE_CONV_ENCODING`` Automatically convert message catalogs to platform's default encoding. Note that it will do only basic conversion between well-known pair like iso8859-1 and windows-1252 or iso8859-2 and windows-1250. Note that this flag is meaningless in Unicode build. =================================== ======================================= | 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 `wx.Locale` object becomes the new current global locale for the application and so all subsequent calls to `wx.GetTranslation() <../wxFunctions.html#GetTranslation>`_ will try to translate the messages using the message catalogs for this locale. Returns ``True`` on success or ``False`` if the given locale couldn't be set. **Returns:** `bool` -------- .. method:: Init1(szName, szShort="", szLocale="", bLoadDefault=True, bConvertEncoding=False) | **Parameters:** * `szName` (string): The name of the locale. Only used in diagnostic messages. * `szShort` (string): The standard 2 letter locale abbreviation; it is used as the directory prefix when looking for the message catalog files. * `szLocale` (string): The parameter for the call to `setlocale()`. .. note:: Note that it is platform-specific. * `bLoadDefault` (bool): 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. * `bConvertEncoding` (bool): May be set to ``True`` to do automatic conversion of message catalogs to platform's native encoding. .. note:: Note that it will do only basic conversion between well-known pair like iso8859-1 and windows-1252 or iso8859-2 and windows-1250. | **Returns:** `bool` .. seealso:: `Init <#Init>`_ -------- .. method:: Init2(language=wx.LANGUAGE_DEFAULT, flags=wx.LOCALE_LOAD_DEFAULT|wx.LOCALE_CONV_ENCODING) | **Parameters:** * `language` (int): identifier of the locale. ``wx.LANGUAGE_DEFAULT`` has special meaning -- `wx.Locale` will use system's default language (see `GetSystemLanguage <#GetSystemLanguage>`_). * `flags` (int): Combination of the following: =================================== ======================================= Locale Flags Description =================================== ======================================= ``wx.LOCALE_LOAD_DEFAULT`` Load the message catalog for the given locale containing the translations of standard wxWidgets messages automatically. ``wx.LOCALE_CONV_ENCODING`` Automatically convert message catalogs to platform's default encoding. Note that it will do only basic conversion between well-known pair like iso8859-1 and windows-1252 or iso8859-2 and windows-1250. Note that this flag is meaningless in Unicode build. =================================== ======================================= | 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 `wx.Locale` object becomes the new current global locale for the application and so all subsequent calls to `wx.GetTranslation() <../wxFunctions.html#GetTranslation>`_ will try to translate the messages using the message catalogs for this locale. Returns ``True`` on success or ``False`` if the given locale couldn't be set. | **Returns:** `bool` .. seealso:: `Init <#Init>`_ -------- .. method:: 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 `wx.Language` identifier. To obtain this for a given a two letter ISO language code, use `FindLanguageInfo <#FindLanguageInfo>`_ to obtain its `wx.LanguageInfo` structure. This function is new since wxWidgets version 2.7.1. **Parameters:** * `lang` (int) | **Returns:** `bool` .. seealso:: `AddLanguage <#AddLanguage>`_ -------- .. method:: IsLoaded(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. **Parameters:** * `domain` (string) | **Returns:** `bool` .. seealso:: `AddCatalog <#AddCatalog>`_ -------- .. method:: IsOk() Returns ``True`` if the locale could be set successfully. | **Returns:** `bool` -------- Properties ^^^^^^^^^^ .. attribute:: CanonicalName See `GetCanonicalName <#GetCanonicalName>`_ .. attribute:: Language See `GetLanguage <#GetLanguage>`_ .. attribute:: Locale See `GetLocale <#GetLocale>`_ .. attribute:: Name See `GetName <#GetName>`_ .. attribute:: String See `GetString <#GetString>`_ .. attribute:: SysName See `GetSysName <#GetSysName>`_