wxRuby Documentation Home

# Wx::Locale

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.

## See also

Internationalization overview,

Internat sample

## Methods

### Class Methods

- Locale#find_language_info
- Locale#get_language_info
- Locale#get_language_name
- Locale.get_system_encoding
- Locale.get_system_encoding_name
- Locale.get_system_language
- Locale.is_available
- Locale.new

### Instance Methods

- Supported languages
- Locale#add_catalog
- Locale#add_catalog_lookup_path_prefix
- Locale#add_language
- Locale#get_canonical_name
- Locale#get_language
- Locale#get_locale
- Locale#get_name
- Locale#get_string
- Locale#get_header_value
- Locale#get_sys_name
- Locale#init
- Locale#is_loaded
- Locale#is_ok

## Class Methods

### Locale.find_language_info

LanguageInfo find_language_info(%(arg-type)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.

#### See also

get_language_info

### Locale.get_language_info

LanguageInfo get_language_info(%(arg-type)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.

### Locale.get_system_encoding_name

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.

### Locale.get_system_language

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.

### Locale.get_system_language_name

String get_system_language_name()

Returns the name of the user’s default langage. Returns an uppercase
String name, for example “ENGLISH_UK”.

### Locale.is_available

Boolean is_available(%(arg-type)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

Locale.new(%(arg-type)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.set_locale

Locale.new(%(arg-type)Integer% language) Locale.new(%(arg-type)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.

## Instance Methods

### Locale#add_catalog

Boolean add_catalog(%(arg-type)char% szDomain) Boolean add_catalog(%(arg-type)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
(i.e. arguments to get_string,
GetTranslation and the
_ 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.

### Locale#add_catalog_lookup_path_prefix

add_catalog_lookup_path_prefix(%(arg-type)String% prefix)

Add a prefix to the catalog lookup path: the message catalog files will be
looked up under prefix/<lang>/LC_MESSAGES, prefix/<lang> and prefix
(in this order).

This only applies to subsequent invocations of AddCatalog().

### Locale#add_language

add_language(%(arg-type)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:

- language (Integer language identifier id)
- canonical_name (Canonical name, eg fr_FR)
- description (Human readable string name of the language)

The value of Language should be greater than `Wx::LANGUAGE_USER_DEFINED`.

### Locale#get_canonical_name

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.

### Locale#get_language

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.

### Locale#get_language_name

String get_language_name(%(arg-type)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`.

### Locale#get_locale

String get_locale()

Returns the locale name as passed to the constructor. This is full,
human-readable name, e.g. “English” or “French”.

### Locale#get_name

String get_name()

Returns the current short name for the locale.

### Locale#get_string

char get_string(%(arg-type)char% szOrigString, char szDomain = nil) char get_string(%(arg-type)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.

#### Remarks

Domains are searched in the last to first order, i.e. catalogs
added later override those added before.

### Locale#get_header_value

String get_header_value(%(arg-type)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.

### Locale#get_sys_name

String get_sys_name()

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

Compare get_canonical_name.

### Locale#get_system_encoding

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.

### Locale#init

Boolean init(%(arg-type)Integer% language = LANGUAGE_DEFAULT, Integer flags = LOCALE_LOAD_DEFAULT | LOCALE_CONV_ENCODING) Boolean init(%(arg-type)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.

#### Parameters

- language Language identifier of the locale.
  LANGUAGE_DEFAULT has special meaning — Locale will use system’s default
  language (see get_system_language).
- flags Combination of the following:

`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.

- szName The name of the locale. Only used in diagnostic messages.
- szShort The standard 2 letter locale abbreviation; it is used as the
  directory prefix when looking for the message catalog files.
- szLocale The parameter for the call to setlocale(). Note that it is
  platform-specific.
- bLoadDefault May be set to false to prevent loading of the message catalog
  for the given locale containing the translations of standard Widgets messages.
  This parameter would be rarely used in normal circumstances.
- bConvertEncoding May be set to true to do automatic conversion of message
  catalogs to platform’s native 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.
  See Writing non-English applications for detailed
  description of this behaviour.

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.

### Locale#is_loaded

Boolean is_loaded(%(arg-type)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

### Locale#is_ok

Boolean is_ok()

Returns true if the locale could be set successfully.

[This page automatically generated from the Textile source at 2023-06-09 00:45:28 +0000]