1
\section{\class{wxLocale}}\label{wxlocale}
3
wxLocale class encapsulates all language-dependent settings and is a
4
generalization of the C locale concept.
6
In wxWidgets this class manages message catalogs which contain the translations
7
of the strings used to the current language.
9
\perlnote{In wxPerl you can't use the '\_' function name, so
10
the {\tt Wx::Locale} module can export the {\tt gettext} and
11
{\tt gettext\_noop} under any given name.
14
# this imports gettext ( equivalent to Wx::GetTranslation
15
# and gettext_noop ( a noop )
17
use Wx::Locale qw(:default);
22
print gettext( ``Panic!'' );
24
button = Wx::Button->new( window, -1, gettext( ``Label'' ) );
27
If you need to translate a lot of strings, then adding gettext( ) around
28
each one is a long task ( that is why \_( ) was introduced ), so just choose
29
a shorter name for gettext:
33
use Wx::Locale 'gettext' => 't',
34
'gettext_noop' => 'gettext_noop';
39
print t( ``Panic!!'' );
45
\wxheading{Derived from}
51
\helpref{Internationalization overview}{internationalization},\\
52
\helpref{Internat sample}{sampleinternat}
54
\wxheading{Include files}
59
\latexignore{\rtfignore{\wxheading{Members}}}
63
\membersection{Supported languages}\label{wxlanguage}
65
See \helpref{list of recognized language constants}{languagecodes}.
66
These constants may be used to specify the language
67
in \helpref{Init}{wxlocaleinit} and are returned by
68
\helpref{GetSystemLanguage}{wxlocalegetsystemlanguage}:
71
\membersection{wxLocale::wxLocale}\label{wxlocaledefctor}
73
\func{}{wxLocale}{\void}
75
This is the default constructor and it does nothing to initialize the object:
76
\helpref{Init()}{wxlocaleinit} must be used to do that.
78
\func{}{wxLocale}{\param{int }{language}, \param{int }{flags =
79
wxLOCALE\_LOAD\_DEFAULT | wxLOCALE\_CONV\_ENCODING}}
81
See \helpref{Init()}{wxlocaleinit} for parameters description.
83
\func{}{wxLocale}{\param{const char }{*szName}, \param{const char }{*szShort = NULL}, \param{const char }{*szLocale = NULL}, \param{bool }{bLoadDefault = true}, \param{bool }{bConvertEncoding = false}}
85
See \helpref{Init()}{wxlocaleinit} for parameters description.
87
The call of this function has several global side effects which you should
88
understand: first of all, the application locale is changed - note that this
89
will affect many of standard C library functions such as printf() or strftime().
90
Second, this wxLocale object becomes the new current global locale for the
91
application and so all subsequent calls to wxGetTranslation() will try to
92
translate the messages using the message catalogs for this locale.
96
\membersection{wxLocale::\destruct{wxLocale}}\label{wxlocaledtor}
98
\func{}{\destruct{wxLocale}}{\void}
100
The destructor, like the constructor, also has global side effects: the previously
101
set locale is restored and so the changes described in
102
\helpref{Init}{wxlocaleinit} documentation are rolled back.
105
\membersection{wxLocale::AddCatalog}\label{wxlocaleaddcatalog}
107
\func{bool}{AddCatalog}{\param{const char }{*szDomain}}
109
\func{bool}{AddCatalog}{\param{const char }{*szDomain}, \param{wxLanguage}{msgIdLanguage}, \param{const char }{*msgIdCharset}}
111
Add a catalog for use with the current locale: it is searched for in standard
112
places (current directory first, then the system one), but you may also prepend
113
additional directories to the search path with
114
\helpref{AddCatalogLookupPathPrefix()}{wxlocaleaddcataloglookuppathprefix}.
116
All loaded catalogs will be used for message lookup by
117
\helpref{GetString()}{wxlocalegetstring} for the current locale.
119
Returns true if catalog was successfully loaded, false otherwise (which might
120
mean that the catalog is not found or that it isn't in the correct format).
122
The second form of this method takes two additional arguments,
123
\arg{msgIdLanguage} and \arg{msgIdCharset}.
125
\arg{msgIdLanguage} specifies the language of "msgid" strings in source code
126
(i.e. arguments to \helpref{GetString}{wxlocalegetstring},
127
\helpref{wxGetTranslation}{wxgettranslation} and the
128
\helpref{\_()}{underscore} macro). It is used if AddCatalog cannot find any
129
catalog for current language: if the language is same as source code language,
130
then strings from source code are used instead.
132
\arg{msgIdCharset} lets you specify the charset used for msgids in sources
133
in case they use 8-bit characters (e.g. German or French strings). This
134
argument has no effect in Unicode build, because literals in sources are
135
Unicode strings; you have to use compiler-specific method of setting the right
136
charset when compiling with Unicode.
138
By default (i.e. when you use the first form), msgid strings are assumed
139
to be in English and written only using 7-bit ASCII characters.
141
If you have to deal with non-English strings or 8-bit characters in the source
142
code, see the instructions in
143
\helpref{Writing non-English applications}{nonenglishoverview}.
146
\membersection{wxLocale::AddCatalogLookupPathPrefix}\label{wxlocaleaddcataloglookuppathprefix}
148
\func{void}{AddCatalogLookupPathPrefix}{\param{const wxString\& }{prefix}}
150
Add a prefix to the catalog lookup path: the message catalog files will be
151
looked up under prefix/<lang>/LC\_MESSAGES, prefix/<lang> and prefix
154
This only applies to subsequent invocations of AddCatalog().
156
\membersection{wxLocale::AddLanguage}\label{wxlocaleaddlanguage}
158
\func{static void}{AddLanguage}{\param{const wxLanguageInfo\& }{info}}
160
Adds custom, user-defined language to the database of known languages. This
161
database is used in conjunction with the first form of
162
\helpref{Init}{wxlocaleinit}.
164
wxLanguageInfo is defined as follows:
167
struct WXDLLEXPORT wxLanguageInfo
169
int Language; // wxLanguage id
170
wxString CanonicalName; // Canonical name, e.g. fr_FR
172
wxUint32 WinLang, WinSublang; // Win32 language identifiers
173
// (LANG_xxxx, SUBLANG_xxxx)
175
wxString Description; // human-readable name of the language
180
{\it Language} should be greater than wxLANGUAGE\_USER\_DEFINED.
182
\perlnote{In wxPerl Wx::LanguageInfo has only one method:\par
183
Wx::LanguageInfo->new( language, canonicalName, WinLang, WinSubLang, Description )}
186
\membersection{wxLocale::FindLanguageInfo}\label{wxlocalefindlanguageinfo}
188
\func{static wxLanguageInfo *}{FindLanguageInfo}{\param{const wxString\& }{locale}}
190
This function may be used to find the language description structure for the
191
given locale, specified either as a two letter ISO language code (for example,
192
"pt"), a language code followed by the country code ("pt\_BR") or a full, human
193
readable, language description ("Portuguese-Brazil").
195
Returns the information for the given language or {\tt NULL} if this language
196
is unknown. Note that even if the returned pointer is valid, the caller should
201
\helpref{GetLanguageInfo}{wxlocalegetlanguageinfo}
204
\membersection{wxLocale::GetCanonicalName}\label{wxlocalegetcanonicalname}
206
\constfunc{wxString}{GetCanonicalName}{\void}
208
Returns the canonical form of current locale name. Canonical form is the
209
one that is used on UNIX systems: it is a two- or five-letter string in xx or
210
xx\_YY format, where xx is ISO 639 code of language and YY is ISO 3166 code of
211
the country. Examples are "en", "en\_GB", "en\_US" or "fr\_FR".
213
This form is internally used when looking up message catalogs.
215
Compare \helpref{GetSysName}{wxlocalegetsysname}.
220
\membersection{wxLocale::GetLanguage}\label{wxlocalegetlanguage}
222
\constfunc{int}{GetLanguage}{\void}
224
Returns \helpref{wxLanguage}{wxlanguage} constant of current language.
225
Note that you can call this function only if you used the form of
226
\helpref{Init}{wxlocaleinit} that takes wxLanguage argument.
229
\membersection{wxLocale::GetLanguageInfo}\label{wxlocalegetlanguageinfo}
231
\constfunc{static wxLanguageInfo *}{GetLanguageInfo}{\param{int }{lang}}
233
Returns a pointer to wxLanguageInfo structure containing information about the
234
given language or {\tt NULL} if this language is unknown. Note that even if the
235
returned pointer is valid, the caller should {\it not} delete it.
237
See \helpref{AddLanguage}{wxlocaleaddlanguage} for the wxLanguageInfo
240
As with \helpref{Init}{wxlocaleinit}, \texttt{wxLANGUAGE\_DEFAULT} has the
241
special meaning if passed as an argument to this function and in this case the
242
result of \helpref{GetSystemLanguage()}{wxlocalegetsystemlanguage} is used.
245
\membersection{wxLocale::GetLanguageName}\label{wxlocalegetlanguagename}
247
\constfunc{static wxString}{GetLanguageName}{\param{int }{lang}}
249
Returns English name of the given language or empty string if this
252
See \helpref{GetLanguageInfo}{wxlocalegetlanguageinfo} for a remark about
253
special meaning of \texttt{wxLANGUAGE\_DEFAULT}.
256
\membersection{wxLocale::GetLocale}\label{wxlocalegetlocale}
258
\constfunc{const char*}{GetLocale}{\void}
260
Returns the locale name as passed to the constructor or
261
\helpref{Init()}{wxlocaleinit}. This is full, human-readable name,
262
e.g. "English" or "French".
266
\membersection{wxLocale::GetName}\label{wxlocalegetname}
268
\constfunc{const wxString\&}{GetName}{\void}
270
Returns the current short name for the locale (as given to the constructor or
271
the Init() function).
274
\membersection{wxLocale::GetString}\label{wxlocalegetstring}
276
\constfunc{const char*}{GetString}{\param{const char }{*szOrigString}, \param{const char }{*szDomain = NULL}}
278
\constfunc{const char*}{GetString}{\param{const char }{*szOrigString}, \param{const char }{*szOrigString2}, \param{size\_t }{n}, \param{const char }{*szDomain = NULL}}
280
Retrieves the translation for a string in all loaded domains unless the szDomain
281
parameter is specified (and then only this catalog/domain is searched).
283
Returns original string if translation is not available
284
(in this case an error message is generated the first time
285
a string is not found; use \helpref{wxLogNull}{wxlogoverview} to suppress it).
287
The second form is used when retrieving translation of string that has
288
different singular and plural form in English or different plural forms in some
289
other language. It takes two extra arguments: \arg{szOrigString}
290
parameter must contain the singular form of the string to be converted.
291
It is also used as the key for the search in the catalog.
292
The \arg{szOrigString2} parameter is the plural form (in English).
293
The parameter \arg{n} is used to determine the plural form. If no
294
message catalog is found \arg{szOrigString} is returned if `n == 1',
295
otherwise \arg{szOrigString2}.
296
See \urlref{GNU gettext manual}{http://www.gnu.org/manual/gettext/html\_chapter/gettext\_10.html\#SEC150} for additional information on plural forms handling.
298
This method is called by the \helpref{wxGetTranslation}{wxgettranslation}
299
function and \helpref{\_()}{underscore} macro.
303
Domains are searched in the last to first order, i.e. catalogs
304
added later override those added before.
307
\membersection{wxLocale::GetHeaderValue}\label{wxlocalegetheadervalue}
309
\constfunc{wxString}{GetHeaderValue}{\param{const char }{*szHeader}, \param{const char }{*szDomain = NULL}}
311
Returns the header value for header \arg{szHeader}. The search for \arg{szHeader} is case sensitive. If an \arg{szDomain}
312
is passed, this domain is searched. Else all domains will be searched until a header has been found.
313
The return value is the value of the header if found. Else this will be empty.
315
\membersection{wxLocale::GetSysName}\label{wxlocalegetsysname}
317
\constfunc{wxString}{GetSysName}{\void}
319
Returns current platform-specific locale name as passed to setlocale().
321
Compare \helpref{GetCanonicalName}{wxlocalegetcanonicalname}.
325
\membersection{wxLocale::GetSystemEncoding}\label{wxlocalegetsystemencoding}
327
\constfunc{static wxFontEncoding}{GetSystemEncoding}{\void}
329
Tries to detect the user's default font encoding.
330
Returns \helpref{wxFontEncoding}{wxfont} value or
331
{\bf wxFONTENCODING\_SYSTEM} if it couldn't be determined.
334
\membersection{wxLocale::GetSystemEncodingName}\label{wxlocalegetsystemencodingname}
336
\constfunc{static wxString}{GetSystemEncodingName}{\void}
338
Tries to detect the name of the user's default font encoding. This string isn't
339
particularly useful for the application as its form is platform-dependent and
340
so you should probably use
341
\helpref{GetSystemEncoding}{wxlocalegetsystemencoding} instead.
343
Returns a user-readable string value or an empty string if it couldn't be
347
\membersection{wxLocale::GetSystemLanguage}\label{wxlocalegetsystemlanguage}
349
\constfunc{static int}{GetSystemLanguage}{\void}
351
Tries to detect the user's default language setting.
352
Returns \helpref{wxLanguage}{wxlanguage} value or
353
{\bf wxLANGUAGE\_UNKNOWN} if the language-guessing algorithm failed.
357
\membersection{wxLocale::Init}\label{wxlocaleinit}
360
\func{bool}{Init}{\param{int }{language = wxLANGUAGE\_DEFAULT}, \param{int }{flags =
361
wxLOCALE\_LOAD\_DEFAULT | wxLOCALE\_CONV\_ENCODING}}
363
\func{bool}{Init}{\param{const char }{*szName}, \param{const char }{*szShort = NULL}, \param{const char }{*szLocale = NULL}, \param{bool }{bLoadDefault = true}, \param{bool }{bConvertEncoding = false}}
365
The second form is deprecated, use the first one unless you know what you are
369
\wxheading{Parameters}
371
\docparam{language}{\helpref{wxLanguage}{wxlanguage} identifier of the locale.
372
wxLANGUAGE\_DEFAULT has special meaning -- wxLocale will use system's default
373
language (see \helpref{GetSystemLanguage}{wxlocalegetsystemlanguage}).}
375
\docparam{flags}{Combination of the following:
378
\begin{twocollist}\itemsep=0pt
379
\twocolitem{\windowstyle{wxLOCALE\_LOAD\_DEFAULT}}{Load the message catalog
380
for the given locale containing the translations of standard wxWidgets messages
382
\twocolitem{\windowstyle{wxLOCALE\_CONV\_ENCODING}}{Automatically convert message
383
catalogs to platform's default encoding. Note that it will do only basic
384
conversion between well-known pair like iso8859-1 and windows-1252 or
385
iso8859-2 and windows-1250. See \helpref{Writing non-English applications}{nonenglishoverview} for detailed
386
description of this behaviour. Note that this flag is meaningless in Unicode build.}
390
\docparam{szName}{The name of the locale. Only used in diagnostic messages.}
392
\docparam{szShort}{The standard 2 letter locale abbreviation; it is used as the
393
directory prefix when looking for the message catalog files.}
395
\docparam{szLocale}{The parameter for the call to setlocale(). Note that it is
398
\docparam{bLoadDefault}{May be set to false to prevent loading of the message catalog
399
for the given locale containing the translations of standard wxWidgets messages.
400
This parameter would be rarely used in normal circumstances.}
402
\docparam{bConvertEncoding}{May be set to true to do automatic conversion of message
403
catalogs to platform's native encoding. Note that it will do only basic
404
conversion between well-known pair like iso8859-1 and windows-1252 or
405
iso8859-2 and windows-1250.
406
See \helpref{Writing non-English applications}{nonenglishoverview} for detailed
407
description of this behaviour.}
410
The call of this function has several global side effects which you should
411
understand: first of all, the application locale is changed - note that this
412
will affect many of standard C library functions such as printf() or strftime().
413
Second, this wxLocale object becomes the new current global locale for the
414
application and so all subsequent calls to
415
\helpref{wxGetTranslation()}{wxgettranslation} will try to
416
translate the messages using the message catalogs for this locale.
418
Returns true on success or false if the given locale couldn't be set.
421
\membersection{wxLocale::IsLoaded}\label{wxlocaleisloaded}
423
\constfunc{bool}{IsLoaded}{\param{const char* }{domain}}
425
Check if the given catalog is loaded, and returns true if it is.
427
According to GNU gettext tradition, each catalog
428
normally corresponds to 'domain' which is more or less the application name.
430
See also: \helpref{AddCatalog}{wxlocaleaddcatalog}
433
\membersection{wxLocale::IsOk}\label{wxlocaleisok}
435
\constfunc{bool}{IsOk}{\void}
437
Returns true if the locale could be set successfully.
added
removed
docs/latex/wx/locale.tex
