The Locale class encapsulates all language-dependent settings and is a
generalization of the C locale concept. This class’s methods may be used
to discover information about the user’s default language, such as its
canonical name, description and character encoding. It may also be used
to set an alternative locale, via Wx::Locale.set_locale. This will
affect things like the default date format.
In WxWidgets this class also manages message catalogs which contain
translations of the strings used for the current language. However, the
methods for getting translations of strings (get_string, add_catalog
etc) are not currently supported in wxRuby.
Internationalization overview,
LanguageInfo find_language_info(String 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 nil if this language
is unknown.
LanguageInfo get_language_info(Integer lang)Returns a pointer to LanguageInfo structure containing information about the
given language or NULL if this language is unknown. Note that even if the
returned pointer is valid, the caller should not delete it.
See add_language for the LanguageInfo description.
As with Init, LANGUAGE_DEFAULT has the
special meaning if passed as an argument to this function and in this case the
result of get_system_language()() is used.
String get_system_encoding_name()Returns the name of the user’s default font encoding, for example ‘ISO-8859-1’. Nil is returned if the system encoding couldn’t be detected.
Integer get_system_language()Tries to detect the user’s default language setting. Returns
Language, for example Wx::LANGUAGE_ENGLISH_UK value or
1 (Wx::LANGUAGE_UNKNOWN) if the language-guessing algorithm failed.
String get_system_language_name()Returns the name of the user’s default langage. Returns an uppercase String name, for example “ENGLISH_UK”.
Boolean is_available(Integer language)Check whether the operating system and/or C run time environment supports this locale. For example in Windows 2000 and Windows XP, as well as on popular Linux desktop distributions, support for many locales is not installed by default. Calling set_locale on an uninstalled Locale may cause error messages to be displayed to the user.
Returns true if the locale is supported.
The argument language is the Integer wxLanguage identifier. To obtain
this for a given a two letter ISO language code, use
find_language_info to obtain its
Wx::LanguageInfo structure. See add_language for
the Wx::LanguageInfo description.
Locale.new(Integer language,
Integer flags = LOCALE_LOAD_DEFAULT|LOCALE_CONV_ENCODING)Creates a new Wx::Locale object, and sets it to be the global locale used by this location. See Locale.set_locale.
Locale.new(Integer language)Locale.new(String language)Sets language to be the default language for this
application. language may be a Wx::LANGUAGE_XXX constant (for example,
Wx::LANGUAGE_DUTCH) or a canonical name (for example, ‘pt_BR’, for
Brazilian Portuguese).
The call of this function has several global effects which you should understand: first of all, the application locale is changed - note that this will affect standard ruby methods such as Time#strftime.
Boolean add_catalog(char szDomain)Boolean add_catalog(char szDomain, Language msgIdLanguage,
char msgIdCharset)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 add_catalog_lookup_path_prefix()().
All loaded catalogs will be used for message lookup by get_string()() 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).
The second form of this method takes two additional arguments, msgIdLanguage and msgIdCharset.
msgIdLanguage specifies the language of “msgid strings in source code macro). It is used if 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.
msgIdCharset lets you specify the charset used for msgids in sources in case they use 8-bit characters (e.g. German or French strings). This argument has no effect in Unicode build, because literals in sources are Unicode strings; you have to use compiler-specific method of setting the right charset when compiling with Unicode.
By default (i.e. when you use the first form), 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 Writing non-English applications.
add_catalog_lookup_path_prefix(String prefix)Add a prefix to the catalog lookup path: the message catalog files will be
looked up under prefix/
This only applies to subsequent invocations of AddCatalog().
add_language(LanguageInfo info)Adds custom, user-defined language to the database of known languages. This database is used in conjunction with the first form of Init.
LanguageInfo is a Ruby struct class with the following accessors:
The value of Language should be greater than Wx::LANGUAGE_USER_DEFINED.
String get_canonical_name()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 get_sys_name.
Integer get_language()Returns Language constant of current language. Note that you can call this function only if you used the form of Init that takes Language argument.
String get_language_name(Integer lang)Returns English name of the given language or empty string if this language is unknown.
See get_language_info for a remark about
special meaning of LANGUAGE_DEFAULT.
String get_locale()Returns the locale name as passed to the constructor. This is full, human-readable name, e.g. “English” or “French”.
String get_name()Returns the current short name for the locale.
char get_string(char szOrigString, char szDomain = nil)char get_string(char szOrigString, char szOrigString2,
Integer n,
char szDomain = nil)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 LogNull to suppress it).
The second 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. It takes two extra arguments: szOrigString parameter must contain the singular form of the string to be converted. It is also used as the key for the search in the catalog. The szOrigString2 parameter is the plural form (in English). The parameter n is used to determine the plural form. If no message catalog is found szOrigString is returned if `n == 1’, otherwise szOrigString2. See GNU gettext manualhttp://www.gnu.org/manual/gettext/html_chapter/gettext_10.html\#SEC150 for additional information on plural forms handling.
This method is called by the GetTranslation function and _() macro.
Domains are searched in the last to first order, i.e. catalogs added later override those added before.
String get_header_value(char szHeader, char szDomain = nil)Returns the header value for header szHeader. The search for szHeader is case sensitive. If an szDomain 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.
String get_sys_name()Returns current platform-specific locale name as passed to setlocale().
Compare get_canonical_name.
FontEncoding get_system_encoding()Tries to detect the user’s default font encoding. Returns FontEncoding value or FONTENCODING_SYSTEM if it couldn’t be determined.
Boolean init(Integer language = LANGUAGE_DEFAULT,
Integer flags = LOCALE_LOAD_DEFAULT | LOCALE_CONV_ENCODING)Boolean init(char szName, char szShort = nil,
char szLocale = nil,
Boolean bLoadDefault = true,
Boolean bConvertEncoding = false)The second form is deprecated, use the first one unless you know what you are doing.
LOCALE_LOAD_DEFAULT |
Load the message catalogfor the given locale containing the translations of standard Widgets messagesautomatically. |
LOCALE_CONV_ENCODING |
Automatically convert messagecatalogs to platform’s default encoding. Note that it will do only basic conversion between well-known pair like iso8859-1 and windows-1252 oriso8859-2 and windows-1250. See Writing non-English applications for detaileddescription of this behaviour. 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 Locale object becomes the new current global locale for the application and so all subsequent calls to 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.
Boolean is_loaded(char 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.
See also: add_catalog
Boolean is_ok()Returns true if the locale could be set successfully.
[This page automatically generated from the Textile source at Thu May 01 00:50:40 +0100 2008]