]> git.saurik.com Git - wxWidgets.git/blame - interface/intl.h
Minor correction
[wxWidgets.git] / interface / intl.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: intl.h
e54c96f1 3// Purpose: interface of wxLocale
23324ae1
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
9/**
10 @class wxLocale
11 @wxheader{intl.h}
7c913512 12
23324ae1
FM
13 wxLocale class encapsulates all language-dependent settings and is a
14 generalization of the C locale concept.
7c913512 15
23324ae1
FM
16 In wxWidgets this class manages message catalogs which contain the translations
17 of the strings used to the current language.
7c913512 18
23324ae1 19 @b wxPerl note: In wxPerl you can't use the '_' function name, so
7c913512
FM
20 the @c Wx::Locale module can export the @c gettext and
21 @c gettext_noop under any given name.
22
23324ae1
FM
23 @code
24 # this imports gettext ( equivalent to Wx::GetTranslation
25 # and gettext_noop ( a noop )
26 # into your module
27 use Wx::Locale qw(:default);
7c913512 28
23324ae1 29 # ....
7c913512 30
23324ae1 31 # use the functions
cdbcf4c2 32 print gettext( "Panic!" );
7c913512 33
cdbcf4c2 34 button = Wx::Button-new( window, -1, gettext( "Label" ) );
23324ae1 35 @endcode
7c913512 36
23324ae1
FM
37 If you need to translate a lot of strings, then adding gettext( ) around
38 each one is a long task ( that is why _( ) was introduced ), so just choose
39 a shorter name for gettext:
7c913512 40
23324ae1
FM
41 @code
42 #
43 use Wx::Locale 'gettext' = 't',
44 'gettext_noop' = 'gettext_noop';
7c913512 45
23324ae1 46 # ...
7c913512 47
23324ae1 48 # use the functions
cdbcf4c2 49 print t( "Panic!!" );
7c913512 50
23324ae1
FM
51 # ...
52 @endcode
7c913512 53
23324ae1
FM
54 @library{wxbase}
55 @category{FIXME}
7c913512 56
e54c96f1 57 @see @ref overview_internationalization, @ref overview_sampleinternat "Internat
4cc4bfaf 58 sample", wxXLocale
23324ae1 59*/
7c913512 60class wxLocale
23324ae1
FM
61{
62public:
63 //@{
64 /**
65 See Init() for parameters description.
23324ae1
FM
66 The call of this function has several global side effects which you should
67 understand: first of all, the application locale is changed - note that this
68 will affect many of standard C library functions such as printf() or strftime().
69 Second, this wxLocale object becomes the new current global locale for the
70 application and so all subsequent calls to wxGetTranslation() will try to
71 translate the messages using the message catalogs for this locale.
72 */
73 wxLocale();
7c913512
FM
74 wxLocale(int language,
75 int flags =
76 wxLOCALE_LOAD_DEFAULT | wxLOCALE_CONV_ENCODING);
77 wxLocale(const wxString& name,
78 const wxString& short = wxEmptyString,
79 const wxString& locale = wxEmptyString,
4cc4bfaf
FM
80 bool bLoadDefault = true,
81 bool bConvertEncoding = false);
23324ae1
FM
82 //@}
83
84 /**
85 The destructor, like the constructor, also has global side effects: the
86 previously
7c913512 87 set locale is restored and so the changes described in
23324ae1
FM
88 Init() documentation are rolled back.
89 */
90 ~wxLocale();
91
92 //@{
93 /**
94 Add a catalog for use with the current locale: it is searched for in standard
95 places (current directory first, then the system one), but you may also prepend
7c913512 96 additional directories to the search path with
23324ae1 97 AddCatalogLookupPathPrefix().
23324ae1
FM
98 All loaded catalogs will be used for message lookup by
99 GetString() for the current locale.
23324ae1
FM
100 Returns @true if catalog was successfully loaded, @false otherwise (which might
101 mean that the catalog is not found or that it isn't in the correct format).
23324ae1 102 The second form of this method takes two additional arguments,
4cc4bfaf
FM
103 @a msgIdLanguage and @e msgIdCharset.
104 @a msgIdLanguage specifies the language of "msgid" strings in source code
23324ae1 105 (i.e. arguments to GetString(),
e54c96f1
FM
106 wxGetTranslation() and the
107 _() macro). It is used if AddCatalog cannot find any
23324ae1 108 catalog for current language: if the language is same as source code language,
7c913512 109 then strings from source code are used instead.
4cc4bfaf 110 @a msgIdCharset lets you specify the charset used for msgids in sources
23324ae1
FM
111 in case they use 8-bit characters (e.g. German or French strings). This
112 argument has no effect in Unicode build, because literals in sources are
113 Unicode strings; you have to use compiler-specific method of setting the right
114 charset when compiling with Unicode.
23324ae1
FM
115 By default (i.e. when you use the first form), msgid strings are assumed
116 to be in English and written only using 7-bit ASCII characters.
23324ae1 117 If you have to deal with non-English strings or 8-bit characters in the source
7c913512 118 code, see the instructions in
23324ae1
FM
119 @ref overview_nonenglishoverview "Writing non-English applications".
120 */
121 bool AddCatalog(const wxString& domain);
7c913512
FM
122 bool AddCatalog(const wxString& domain,
123 wxLanguage msgIdLanguage,
124 const wxString& msgIdCharset);
23324ae1
FM
125 //@}
126
127 /**
128 Add a prefix to the catalog lookup path: the message catalog files will be
129 looked up under prefix/lang/LC_MESSAGES, prefix/lang and prefix
130 (in this order).
23324ae1
FM
131 This only applies to subsequent invocations of AddCatalog().
132 */
133 void AddCatalogLookupPathPrefix(const wxString& prefix);
134
135 /**
136 Adds custom, user-defined language to the database of known languages. This
7c913512
FM
137 database is used in conjunction with the first form of
138 Init().
23324ae1 139 wxLanguageInfo is defined as follows:
23324ae1 140 @e Language should be greater than wxLANGUAGE_USER_DEFINED.
23324ae1
FM
141 Wx::LanguageInfo-new( language, canonicalName, WinLang, WinSubLang, Description
142 )
143 */
144 static void AddLanguage(const wxLanguageInfo& info);
145
146 /**
147 This function may be used to find the language description structure for the
148 given locale, specified either as a two letter ISO language code (for example,
149 "pt"), a language code followed by the country code ("pt_BR") or a full, human
150 readable, language description ("Portuguese-Brazil").
23324ae1
FM
151 Returns the information for the given language or @NULL if this language
152 is unknown. Note that even if the returned pointer is valid, the caller should
153 @e not delete it.
3c4f71cc 154
4cc4bfaf 155 @see GetLanguageInfo()
23324ae1 156 */
4cc4bfaf 157 static wxLanguageInfo* FindLanguageInfo(const wxString& locale);
23324ae1
FM
158
159 /**
160 Returns the canonical form of current locale name. Canonical form is the
161 one that is used on UNIX systems: it is a two- or five-letter string in xx or
162 xx_YY format, where xx is ISO 639 code of language and YY is ISO 3166 code of
163 the country. Examples are "en", "en_GB", "en_US" or "fr_FR".
23324ae1 164 This form is internally used when looking up message catalogs.
23324ae1
FM
165 Compare GetSysName().
166 */
328f5751 167 wxString GetCanonicalName() const;
23324ae1
FM
168
169 /**
4cc4bfaf 170 Returns the header value for header @e header. The search for @a header is case
23324ae1
FM
171 sensitive. If an @e domain
172 is passed, this domain is searched. Else all domains will be searched until a
173 header has been found.
174 The return value is the value of the header if found. Else this will be empty.
175 */
176 wxString GetHeaderValue(const wxString& header,
328f5751 177 const wxString& domain = wxEmptyString) const;
23324ae1
FM
178
179 /**
e54c96f1 180 Returns wxLanguage() constant of current language.
23324ae1
FM
181 Note that you can call this function only if you used the form of
182 Init() that takes wxLanguage argument.
183 */
328f5751 184 int GetLanguage() const;
23324ae1
FM
185
186 /**
187 Returns a pointer to wxLanguageInfo structure containing information about the
188 given language or @NULL if this language is unknown. Note that even if the
189 returned pointer is valid, the caller should @e not delete it.
23324ae1
FM
190 See AddLanguage() for the wxLanguageInfo
191 description.
23324ae1
FM
192 As with Init(), @c wxLANGUAGE_DEFAULT has the
193 special meaning if passed as an argument to this function and in this case the
194 result of GetSystemLanguage() is used.
195 */
328f5751 196 static wxLanguageInfo* GetLanguageInfo(int lang) const;
23324ae1
FM
197
198 /**
199 Returns English name of the given language or empty string if this
200 language is unknown.
23324ae1
FM
201 See GetLanguageInfo() for a remark about
202 special meaning of @c wxLANGUAGE_DEFAULT.
203 */
328f5751 204 static wxString GetLanguageName(int lang) const;
23324ae1
FM
205
206 /**
7c913512 207 Returns the locale name as passed to the constructor or
23324ae1
FM
208 Init(). This is full, human-readable name,
209 e.g. "English" or "French".
210 */
328f5751 211 const wxString GetLocale() const;
23324ae1
FM
212
213 /**
214 Returns the current short name for the locale (as given to the constructor or
215 the Init() function).
216 */
328f5751 217 const wxString GetName() const;
23324ae1
FM
218
219 //@{
220 /**
221 Retrieves the translation for a string in all loaded domains unless the szDomain
222 parameter is specified (and then only this catalog/domain is searched).
23324ae1
FM
223 Returns original string if translation is not available
224 (in this case an error message is generated the first time
225 a string is not found; use wxLogNull to suppress it).
23324ae1
FM
226 The second form is used when retrieving translation of string that has
227 different singular and plural form in English or different plural forms in some
228 other language. It takes two extra arguments: @e origString
229 parameter must contain the singular form of the string to be converted.
230 It is also used as the key for the search in the catalog.
4cc4bfaf
FM
231 The @a origString2 parameter is the plural form (in English).
232 The parameter @a n is used to determine the plural form. If no
233 message catalog is found @a origString is returned if 'n == 1',
23324ae1
FM
234 otherwise @e origString2.
235 See GNU gettext manual for additional information on plural forms handling.
e54c96f1
FM
236 This method is called by the wxGetTranslation()
237 function and _() macro.
3c4f71cc 238
23324ae1 239 @remarks Domains are searched in the last to first order, i.e. catalogs
4cc4bfaf 240 added later override those added before.
23324ae1
FM
241 */
242 const wxString GetString(const wxString& origString,
328f5751
FM
243 const wxString& domain = wxEmptyString) const;
244 const const wxString& GetString(const wxString& origString,
245 const wxString& origString2,
246 size_t n,
247 const wxString& domain = NULL) const;
23324ae1
FM
248 //@}
249
250 /**
251 Returns current platform-specific locale name as passed to setlocale().
23324ae1
FM
252 Compare GetCanonicalName().
253 */
328f5751 254 wxString GetSysName() const;
23324ae1
FM
255
256 /**
257 Tries to detect the user's default font encoding.
e54c96f1 258 Returns wxFontEncoding() value or
23324ae1
FM
259 @b wxFONTENCODING_SYSTEM if it couldn't be determined.
260 */
328f5751 261 static wxFontEncoding GetSystemEncoding() const;
23324ae1
FM
262
263 /**
264 Tries to detect the name of the user's default font encoding. This string isn't
265 particularly useful for the application as its form is platform-dependent and
7c913512 266 so you should probably use
23324ae1 267 GetSystemEncoding() instead.
23324ae1
FM
268 Returns a user-readable string value or an empty string if it couldn't be
269 determined.
270 */
328f5751 271 static wxString GetSystemEncodingName() const;
23324ae1
FM
272
273 /**
274 Tries to detect the user's default language setting.
e54c96f1 275 Returns wxLanguage() value or
23324ae1
FM
276 @b wxLANGUAGE_UNKNOWN if the language-guessing algorithm failed.
277 */
328f5751 278 static int GetSystemLanguage() const;
23324ae1
FM
279
280 //@{
281 /**
282 The second form is deprecated, use the first one unless you know what you are
7c913512 283 doing.
3c4f71cc 284
7c913512 285 @param language
4cc4bfaf
FM
286 wxLanguage identifier of the locale.
287 wxLANGUAGE_DEFAULT has special meaning -- wxLocale will use system's
288 default
289 language (see GetSystemLanguage).
7c913512 290 @param flags
4cc4bfaf 291 Combination of the following:
3c4f71cc
VS
292
293
294
295
296
297
298
4cc4bfaf 299 wxLOCALE_LOAD_DEFAULT
3c4f71cc
VS
300
301
302
303
4cc4bfaf
FM
304 Load the message catalog
305 for the given locale containing the translations of standard wxWidgets
306 messages
307 automatically.
3c4f71cc
VS
308
309
310
311
312
4cc4bfaf 313 wxLOCALE_CONV_ENCODING
3c4f71cc
VS
314
315
316
317
4cc4bfaf
FM
318 Automatically convert message
319 catalogs to platform's default encoding. Note that it will do only basic
320 conversion between well-known pair like iso8859-1 and windows-1252 or
321 iso8859-2 and windows-1250. See Writing non-English applications for
322 detailed
323 description of this behaviour. Note that this flag is meaningless in
324 Unicode build.
325 @param name
326 The name of the locale. Only used in diagnostic messages.
327 @param short
328 The standard 2 letter locale abbreviation; it is used as the
329 directory prefix when looking for the message catalog files.
330 @param locale
331 The parameter for the call to setlocale(). Note that it is
332 platform-specific.
333 @param bLoadDefault
334 May be set to @false to prevent loading of the message catalog
335 for the given locale containing the translations of standard wxWidgets
336 messages.
337 This parameter would be rarely used in normal circumstances.
7c913512 338 @param bConvertEncoding
4cc4bfaf
FM
339 May be set to @true to do automatic conversion of message
340 catalogs to platform's native encoding. Note that it will do only basic
341 conversion between well-known pair like iso8859-1 and windows-1252 or
342 iso8859-2 and windows-1250.
343 See Writing non-English applications for detailed
344 description of this behaviour.
23324ae1
FM
345 */
346 bool Init(int language = wxLANGUAGE_DEFAULT,
347 int flags =
7c913512
FM
348 wxLOCALE_LOAD_DEFAULT | wxLOCALE_CONV_ENCODING);
349 bool Init(const wxString& name,
350 const wxString& short = wxEmptyString,
351 const wxString& locale = wxEmptyString,
4cc4bfaf
FM
352 bool bLoadDefault = true,
353 bool bConvertEncoding = false);
23324ae1
FM
354 //@}
355
356 /**
357 Check whether the operating system and/or C run time environment supports
358 this locale. For example in Windows 2000 and Windows XP, support for many
359 locales is not installed by default. Returns @true if the locale is
360 supported.
4cc4bfaf 361 The argument @a lang is the wxLanguage identifier. To obtain this for a
7c913512 362 given a two letter ISO language code, use
23324ae1
FM
363 FindLanguageInfo() to obtain its
364 wxLanguageInfo structure. See AddLanguage() for
365 the wxLanguageInfo description.
3c4f71cc 366
1e24c2af 367 @since 2.7.1.
23324ae1
FM
368 */
369 static bool IsAvailable(int lang);
370
371 /**
372 Check if the given catalog is loaded, and returns @true if it is.
23324ae1
FM
373 According to GNU gettext tradition, each catalog
374 normally corresponds to 'domain' which is more or less the application name.
23324ae1
FM
375 See also: AddCatalog()
376 */
328f5751 377 bool IsLoaded(const char* domain) const;
23324ae1
FM
378
379 /**
380 Returns @true if the locale could be set successfully.
381 */
328f5751 382 bool IsOk() const;
23324ae1
FM
383
384 /**
385 See @ref overview_languagecodes "list of recognized language constants".
386 These constants may be used to specify the language
7c913512 387 in Init() and are returned by
23324ae1
FM
388 GetSystemLanguage():
389 */
390};
391
392
e54c96f1 393
23324ae1
FM
394/**
395 @class wxXLocale
396 @wxheader{intl.h}
7c913512
FM
397
398
23324ae1
FM
399 wxXLocale::wxXLocale
400 wxXLocale::GetCLocale
401 wxXLocale::IsOk
7c913512
FM
402
403
23324ae1 404 Introduction
7c913512
FM
405
406 This class represents a locale object used by so-called xlocale API. Unlike
23324ae1
FM
407 wxLocale it doesn't provide any non-trivial operations but
408 simply provides a portable wrapper for POSIX @c locale_t type. It exists
409 solely to be provided as an argument to various @c wxFoo_l() functions
410 which are the extensions of the standard locale-dependent functions (hence the
411 name xlocale). These functions do exactly the same thing as the corresponding
412 standard @c foo() except that instead of using the global program locale
413 they use the provided wxXLocale object. For example, if the user runs the
414 program in French locale, the standard @c printf() function will output
415 floating point numbers using decimal comma instead of decimal period. If the
416 program needs to format a floating-point number in a standard format it can
417 use @c wxPrintf_l(wxXLocale::GetCLocale(), "%g", number) to do it.
418 Conversely, if a program wanted to output the number in French locale, even if
419 the current locale is different, it could use wxXLocale(wxLANGUAGE_FRENCH).
7c913512
FM
420
421
23324ae1 422 Availability
7c913512 423
23324ae1
FM
424 This class is fully implemented only under the platforms where xlocale POSIX
425 API or equivalent is available. Currently the xlocale API is available under
426 most of the recent Unix systems (including Linux, various BSD and Mac OS X) and
427 Microsoft Visual C++ standard library provides a similar API starting from
428 version 8 (Visual Studio 2005).
7c913512 429
23324ae1
FM
430 If neither POSIX API nor Microsoft proprietary equivalent are available, this
431 class is still available but works in degraded mode: the only supported locale
432 is the C one and attempts to create wxXLocale object for any other locale will
433 fail. You can use the preprocessor macro @c wxHAS_XLOCALE_SUPPORT to
434 test if full xlocale API is available or only skeleton C locale support is
435 present.
7c913512
FM
436
437 Notice that wxXLocale is new in wxWidgets 2.9.0 and is not compiled in if
23324ae1 438 @c wxUSE_XLOCALE was set to 0 during the library compilation.
7c913512
FM
439
440
23324ae1 441 Locale-dependent functions
7c913512 442
23324ae1 443 Currently the following @c _l-functions are available:
7c913512 444
23324ae1
FM
445 Character classification functions: @c wxIsxxx_l(), e.g.
446 @c wxIsalpha_l(), @c wxIslower_l() and all the others.
447 Character transformation functions: @c wxTolower_l() and
448 @c wxToupper_l()
7c913512 449
23324ae1
FM
450 We hope to provide many more functions (covering numbers, time and formatted
451 IO) in the near future.
7c913512 452
23324ae1
FM
453 @library{wxbase}
454 @category{FIXME}
7c913512 455
e54c96f1 456 @see wxLocale
23324ae1 457*/
7c913512 458class wxXLocale
23324ae1
FM
459{
460public:
461 //@{
462 /**
463 Creates the locale object corresponding to the specified locale string. The
464 locale string is system-dependent, use constructor taking wxLanguage for better
465 portability.
466 */
467 wxLocale();
7c913512 468 wxLocale(wxLanguage lang);
4cc4bfaf 469 wxLocale(const char* loc);
23324ae1
FM
470 //@}
471
472 /**
473 This class is fully implemented only under the platforms where xlocale POSIX
474 API or equivalent is available. Currently the xlocale API is available under
475 most of the recent Unix systems (including Linux, various BSD and Mac OS X) and
476 Microsoft Visual C++ standard library provides a similar API starting from
477 version 8 (Visual Studio 2005).
23324ae1
FM
478 If neither POSIX API nor Microsoft proprietary equivalent are available, this
479 class is still available but works in degraded mode: the only supported locale
480 is the C one and attempts to create wxXLocale object for any other locale will
481 fail. You can use the preprocessor macro @c wxHAS_XLOCALE_SUPPORT to
482 test if full xlocale API is available or only skeleton C locale support is
483 present.
7c913512 484 Notice that wxXLocale is new in wxWidgets 2.9.0 and is not compiled in if
23324ae1
FM
485 @c wxUSE_XLOCALE was set to 0 during the library compilation.
486 */
487
488
489 /**
490 Returns the global object representing the "C" locale. For an even shorter
491 access to this object a global @c wxCLocale variable (implemented as a
492 macro) is provided and can be used instead of calling this method.
493 */
494 static wxXLocale GetCLocale();
495
496 /**
7c913512 497 This class represents a locale object used by so-called xlocale API. Unlike
23324ae1
FM
498 wxLocale it doesn't provide any non-trivial operations but
499 simply provides a portable wrapper for POSIX @c locale_t type. It exists
500 solely to be provided as an argument to various @c wxFoo_l() functions
501 which are the extensions of the standard locale-dependent functions (hence the
502 name xlocale). These functions do exactly the same thing as the corresponding
503 standard @c foo() except that instead of using the global program locale
504 they use the provided wxXLocale object. For example, if the user runs the
505 program in French locale, the standard @c printf() function will output
506 floating point numbers using decimal comma instead of decimal period. If the
507 program needs to format a floating-point number in a standard format it can
508 use @c wxPrintf_l(wxXLocale::GetCLocale(), "%g", number) to do it.
509 Conversely, if a program wanted to output the number in French locale, even if
510 the current locale is different, it could use wxXLocale(wxLANGUAGE_FRENCH).
511 */
512
513
514 /**
515 Returns @true if this object is initialized, i.e. represents a valid locale
7c913512 516 or
23324ae1
FM
517 @false otherwise.
518 */
328f5751 519 bool IsOk() const;
23324ae1
FM
520
521 /**
522 Currently the following @c _l-functions are available:
23324ae1
FM
523 Character classification functions: @c wxIsxxx_l(), e.g.
524 @c wxIsalpha_l(), @c wxIslower_l() and all the others.
525 Character transformation functions: @c wxTolower_l() and
526 @c wxToupper_l()
23324ae1
FM
527 We hope to provide many more functions (covering numbers, time and formatted
528 IO) in the near future.
3c4f71cc 529
4cc4bfaf 530 @see wxLocale
23324ae1
FM
531 */
532};
533
534
e54c96f1 535
23324ae1
FM
536// ============================================================================
537// Global functions/macros
538// ============================================================================
539
3950d49c
BP
540/** @ingroup group_funcmacro_string */
541//@{
542
23324ae1 543/**
3950d49c
BP
544 This macro is identical to _() but for the plural variant of
545 wxGetTranslation().
546
547 @returns A const wxString.
548
549 @header{wx/intl.h}
23324ae1 550*/
3950d49c 551#define wxPLURAL(string, plural, n)
23324ae1
FM
552
553/**
3950d49c
BP
554 This macro doesn't do anything in the program code -- it simply expands to
555 the value of its argument.
556
23324ae1
FM
557 However it does have a purpose which is to mark the literal strings for the
558 extraction into the message catalog created by @c xgettext program. Usually
3950d49c
BP
559 this is achieved using _() but that macro not only marks the string for
560 extraction but also expands into a wxGetTranslation() call which means that
561 it cannot be used in some situations, notably for static array
23324ae1 562 initialization.
3950d49c 563
23324ae1
FM
564 Here is an example which should make it more clear: suppose that you have a
565 static array of strings containing the weekday names and which have to be
3950d49c
BP
566 translated (note that it is a bad example, really, as wxDateTime already
567 can be used to get the localized week day names already). If you write:
4cc4bfaf 568
23324ae1
FM
569 @code
570 static const char * const weekdays[] = { _("Mon"), ..., _("Sun") };
571 ...
572 // use weekdays[n] as usual
573 @endcode
7c913512 574
3950d49c
BP
575 The code wouldn't compile because the function calls are forbidden in the
576 array initializer. So instead you should do this:
4cc4bfaf 577
23324ae1
FM
578 @code
579 static const char * const weekdays[] = { wxTRANSLATE("Mon"), ...,
580 wxTRANSLATE("Sun") };
581 ...
582 // use wxGetTranslation(weekdays[n])
583 @endcode
7c913512 584
23324ae1 585 Note that although the code @b would compile if you simply omit
3950d49c
BP
586 wxTRANSLATE() in the above, it wouldn't work as expected because there
587 would be no translations for the weekday names in the program message
588 catalog and wxGetTranslation() wouldn't find them.
589
590 @returns A const wxChar*.
591
592 @header{wx/intl.h}
23324ae1 593*/
3950d49c 594#define wxTRANSLATE(string)
23324ae1
FM
595
596/**
3950d49c
BP
597 This function returns the translation of @a string in the current
598 @c locale(). If the string is not found in any of the loaded message
599 catalogs (see @ref overview_i18n), the original string is returned. In
600 debug build, an error message is logged -- this should help to find the
601 strings which were not yet translated. If @a domain is specified then only
602 that domain/catalog is searched for a matching string. As this function is
603 used very often, an alternative (and also common in Unix world) syntax is
604 provided: the _() macro is defined to do the same thing as
605 wxGetTranslation().
606
607 This function calls wxLocale::GetString().
608
609 @note This function is not suitable for literal strings in Unicode builds
610 since the literal strings must be enclosed into _T() or wxT() macro
611 which makes them unrecognised by @c xgettext, and so they are not
612 extracted to the message catalog. Instead, use the _() and wxPLURAL()
613 macro for all literal strings.
614
615 @see wxGetTranslation(const wxString&, const wxString&, size_t, const wxString&)
616
617 @header{wx/intl.h}
23324ae1 618*/
3950d49c
BP
619const wxString wxGetTranslation(const wxString& string,
620 const wxString& domain = wxEmptyString);
23324ae1 621
23324ae1 622/**
3950d49c
BP
623 This is an overloaded version of
624 wxGetTranslation(const wxString&, const wxString&), please see its
625 documentation for general information.
626
627 This version is used when retrieving translation of string that has
628 different singular and plural forms in English or different plural forms in
629 some other language. Like wxGetTranslation(const wxString&,const wxString&),
630 the @a string parameter must contain the singular form of the string to be
631 converted and is used as the key for the search in the catalog. The
632 @a plural parameter is the plural form (in English). The parameter @a n is
633 used to determine the plural form. If no message catalog is found,
634 @a string is returned if "n == 1", otherwise @a plural is returned.
635
636 See GNU gettext Manual for additional information on plural forms handling:
637 <http://www.gnu.org/software/gettext/manual/gettext.html#Plural-forms>
638 For a shorter alternative see the wxPLURAL() macro.
639
640 This function calls wxLocale::GetString().
641
642 @header{wx/intl.h}
23324ae1 643*/
3950d49c
BP
644const wxString wxGetTranslation(const wxString& string,
645 const wxString& plural, size_t n,
646 const wxString& domain = wxEmptyString);
647
648/**
649 This macro expands into a call to wxGetTranslation(), so it marks the
650 message for the extraction by @c xgettext just as wxTRANSLATE() does, but
651 also returns the translation of the string for the current locale during
652 execution.
653
654 Don't confuse this with _T()!
655
656 @header{wx/intl.h}
657*/
658const wxString _(const wxString& string);
659
23324ae1
FM
660//@}
661