1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxLocale
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
10 // --- --- --- generated code begins here --- --- ---
13 The languages supported by wxLocale.
15 This enum is generated by misc/languages/genlang.py
16 When making changes, please put them into misc/languages/langtabl.txt
20 /// User's default/preferred language as got from OS.
23 /// Unknown language, returned if wxLocale::GetSystemLanguage fails.
32 wxLANGUAGE_ARABIC_ALGERIA
,
33 wxLANGUAGE_ARABIC_BAHRAIN
,
34 wxLANGUAGE_ARABIC_EGYPT
,
35 wxLANGUAGE_ARABIC_IRAQ
,
36 wxLANGUAGE_ARABIC_JORDAN
,
37 wxLANGUAGE_ARABIC_KUWAIT
,
38 wxLANGUAGE_ARABIC_LEBANON
,
39 wxLANGUAGE_ARABIC_LIBYA
,
40 wxLANGUAGE_ARABIC_MOROCCO
,
41 wxLANGUAGE_ARABIC_OMAN
,
42 wxLANGUAGE_ARABIC_QATAR
,
43 wxLANGUAGE_ARABIC_SAUDI_ARABIA
,
44 wxLANGUAGE_ARABIC_SUDAN
,
45 wxLANGUAGE_ARABIC_SYRIA
,
46 wxLANGUAGE_ARABIC_TUNISIA
,
47 wxLANGUAGE_ARABIC_UAE
,
48 wxLANGUAGE_ARABIC_YEMEN
,
53 wxLANGUAGE_AZERI_CYRILLIC
,
54 wxLANGUAGE_AZERI_LATIN
,
57 wxLANGUAGE_BELARUSIAN
,
68 wxLANGUAGE_CHINESE_SIMPLIFIED
,
69 wxLANGUAGE_CHINESE_TRADITIONAL
,
70 wxLANGUAGE_CHINESE_HONGKONG
,
71 wxLANGUAGE_CHINESE_MACAU
,
72 wxLANGUAGE_CHINESE_SINGAPORE
,
73 wxLANGUAGE_CHINESE_TAIWAN
,
79 wxLANGUAGE_DUTCH_BELGIAN
,
81 wxLANGUAGE_ENGLISH_UK
,
82 wxLANGUAGE_ENGLISH_US
,
83 wxLANGUAGE_ENGLISH_AUSTRALIA
,
84 wxLANGUAGE_ENGLISH_BELIZE
,
85 wxLANGUAGE_ENGLISH_BOTSWANA
,
86 wxLANGUAGE_ENGLISH_CANADA
,
87 wxLANGUAGE_ENGLISH_CARIBBEAN
,
88 wxLANGUAGE_ENGLISH_DENMARK
,
89 wxLANGUAGE_ENGLISH_EIRE
,
90 wxLANGUAGE_ENGLISH_JAMAICA
,
91 wxLANGUAGE_ENGLISH_NEW_ZEALAND
,
92 wxLANGUAGE_ENGLISH_PHILIPPINES
,
93 wxLANGUAGE_ENGLISH_SOUTH_AFRICA
,
94 wxLANGUAGE_ENGLISH_TRINIDAD
,
95 wxLANGUAGE_ENGLISH_ZIMBABWE
,
103 wxLANGUAGE_FRENCH_BELGIAN
,
104 wxLANGUAGE_FRENCH_CANADIAN
,
105 wxLANGUAGE_FRENCH_LUXEMBOURG
,
106 wxLANGUAGE_FRENCH_MONACO
,
107 wxLANGUAGE_FRENCH_SWISS
,
112 wxLANGUAGE_GERMAN_AUSTRIAN
,
113 wxLANGUAGE_GERMAN_BELGIUM
,
114 wxLANGUAGE_GERMAN_LIECHTENSTEIN
,
115 wxLANGUAGE_GERMAN_LUXEMBOURG
,
116 wxLANGUAGE_GERMAN_SWISS
,
118 wxLANGUAGE_GREENLANDIC
,
124 wxLANGUAGE_HUNGARIAN
,
125 wxLANGUAGE_ICELANDIC
,
126 wxLANGUAGE_INDONESIAN
,
127 wxLANGUAGE_INTERLINGUA
,
128 wxLANGUAGE_INTERLINGUE
,
129 wxLANGUAGE_INUKTITUT
,
133 wxLANGUAGE_ITALIAN_SWISS
,
138 wxLANGUAGE_KASHMIRI_INDIA
,
141 wxLANGUAGE_KINYARWANDA
,
151 wxLANGUAGE_LITHUANIAN
,
152 wxLANGUAGE_MACEDONIAN
,
155 wxLANGUAGE_MALAYALAM
,
156 wxLANGUAGE_MALAY_BRUNEI_DARUSSALAM
,
157 wxLANGUAGE_MALAY_MALAYSIA
,
162 wxLANGUAGE_MOLDAVIAN
,
163 wxLANGUAGE_MONGOLIAN
,
166 wxLANGUAGE_NEPALI_INDIA
,
167 wxLANGUAGE_NORWEGIAN_BOKMAL
,
168 wxLANGUAGE_NORWEGIAN_NYNORSK
,
174 wxLANGUAGE_PORTUGUESE
,
175 wxLANGUAGE_PORTUGUESE_BRAZILIAN
,
178 wxLANGUAGE_RHAETO_ROMANCE
,
181 wxLANGUAGE_RUSSIAN_UKRAINE
,
186 wxLANGUAGE_SCOTS_GAELIC
,
188 wxLANGUAGE_SERBIAN_CYRILLIC
,
189 wxLANGUAGE_SERBIAN_LATIN
,
190 wxLANGUAGE_SERBO_CROATIAN
,
195 wxLANGUAGE_SINHALESE
,
198 wxLANGUAGE_SLOVENIAN
,
201 wxLANGUAGE_SPANISH_ARGENTINA
,
202 wxLANGUAGE_SPANISH_BOLIVIA
,
203 wxLANGUAGE_SPANISH_CHILE
,
204 wxLANGUAGE_SPANISH_COLOMBIA
,
205 wxLANGUAGE_SPANISH_COSTA_RICA
,
206 wxLANGUAGE_SPANISH_DOMINICAN_REPUBLIC
,
207 wxLANGUAGE_SPANISH_ECUADOR
,
208 wxLANGUAGE_SPANISH_EL_SALVADOR
,
209 wxLANGUAGE_SPANISH_GUATEMALA
,
210 wxLANGUAGE_SPANISH_HONDURAS
,
211 wxLANGUAGE_SPANISH_MEXICAN
,
212 wxLANGUAGE_SPANISH_MODERN
,
213 wxLANGUAGE_SPANISH_NICARAGUA
,
214 wxLANGUAGE_SPANISH_PANAMA
,
215 wxLANGUAGE_SPANISH_PARAGUAY
,
216 wxLANGUAGE_SPANISH_PERU
,
217 wxLANGUAGE_SPANISH_PUERTO_RICO
,
218 wxLANGUAGE_SPANISH_URUGUAY
,
219 wxLANGUAGE_SPANISH_US
,
220 wxLANGUAGE_SPANISH_VENEZUELA
,
221 wxLANGUAGE_SUNDANESE
,
224 wxLANGUAGE_SWEDISH_FINLAND
,
239 wxLANGUAGE_UKRAINIAN
,
241 wxLANGUAGE_URDU_INDIA
,
242 wxLANGUAGE_URDU_PAKISTAN
,
244 wxLANGUAGE_UZBEK_CYRILLIC
,
245 wxLANGUAGE_UZBEK_LATIN
,
246 wxLANGUAGE_VALENCIAN
,
247 wxLANGUAGE_VIETNAMESE
,
257 /// For custom, user-defined languages.
258 wxLANGUAGE_USER_DEFINED
261 // --- --- --- generated code ends here --- --- ---
266 This is the layout direction stored in wxLanguageInfo and returned by
267 wxApp::GetLayoutDirection(), wxWindow::GetLayoutDirection(),
268 wxDC::GetLayoutDirection() for RTL (right-to-left) languages support.
270 enum wxLayoutDirection
273 wxLayout_LeftToRight
,
278 Encapsulates ::wxLanguage in a OS native lang.desc.
279 translation information
281 struct WXDLLIMPEXP_BASE wxLanguageInfo
283 /// ::wxLanguage id. It should be greater than @c wxLANGUAGE_USER_DEFINED.
286 /// Canonical name of the language, e.g. @c fr_FR.
287 wxString CanonicalName
;
291 Win32 language identifiers (LANG_xxxx, SUBLANG_xxxx).
295 wxUint32 WinLang
, WinSublang
;
298 /// Human-readable name of the language.
299 wxString Description
;
301 /// The layout direction used for this language.
302 wxLayoutDirection LayoutDirection
;
304 /// Return the LCID corresponding to this language.
306 wxUint32
GetLCID() const;
308 /// Return the locale name corresponding to this language usable with
309 /// @c setlocale() on the current system.
310 wxString
GetLocaleName() const;
317 wxLocale class encapsulates all language-dependent settings and is a
318 generalization of the C locale concept.
320 In wxWidgets this class manages message catalogs which contain the translations
321 of the strings used to the current language.
323 For a list of the supported languages, please see ::wxLanguage enum values.
324 These constants may be used to specify the language in wxLocale::Init and
325 are returned by wxLocale::GetSystemLanguage.
328 In wxPerl you can't use the '_' function name, so
329 the @c Wx::Locale module can export the @c gettext and
330 @c gettext_noop under any given name.
333 # this imports gettext ( equivalent to Wx::GetTranslation
334 # and gettext_noop ( a noop )
336 use Wx::Locale qw(:default);
341 print gettext( "Panic!" );
343 button = Wx::Button-new( window, -1, gettext( "Label" ) );
346 If you need to translate a lot of strings, then adding gettext( ) around
347 each one is a long task ( that is why _( ) was introduced ), so just choose
348 a shorter name for gettext:
351 use Wx::Locale 'gettext' = 't',
352 'gettext_noop' = 'gettext_noop';
357 print t( "Panic!!" );
366 @see @ref overview_i18n, @ref page_samples_internat, wxXLocale
372 This is the default constructor and it does nothing to initialize the object:
373 Init() must be used to do that.
378 See Init() for parameters description.
380 wxLocale(int language
,
381 int flags
= wxLOCALE_LOAD_DEFAULT
| wxLOCALE_CONV_ENCODING
);
384 See Init() for parameters description.
386 The call of this function has several global side effects which you should
387 understand: first of all, the application locale is changed - note that this
388 will affect many of standard C library functions such as printf() or strftime().
389 Second, this wxLocale object becomes the new current global locale for the
390 application and so all subsequent calls to ::wxGetTranslation() will try to
391 translate the messages using the message catalogs for this locale.
393 wxLocale(const wxString
& name
,
394 const wxString
& short = wxEmptyString
,
395 const wxString
& locale
= wxEmptyString
,
396 bool bLoadDefault
= true,
397 bool bConvertEncoding
= false);
400 The destructor, like the constructor, also has global side effects: the
401 previously set locale is restored and so the changes described in
402 Init() documentation are rolled back.
407 Add a catalog for use with the current locale: it is searched for in standard
408 places (current directory first, then the system one), but you may also prepend
409 additional directories to the search path with AddCatalogLookupPathPrefix().
411 All loaded catalogs will be used for message lookup by GetString() for
414 In this overload, @c msgid strings are assumed
415 to be in English and written only using 7-bit ASCII characters.
416 If you have to deal with non-English strings or 8-bit characters in the
417 source code, see the instructions in @ref overview_nonenglish.
420 @true if catalog was successfully loaded, @false otherwise (which might
421 mean that the catalog is not found or that it isn't in the correct format).
423 bool AddCatalog(const wxString
& domain
);
426 Add a catalog for use with the current locale: it is searched for in standard
427 places (current directory first, then the system one), but you may also prepend
428 additional directories to the search path with AddCatalogLookupPathPrefix().
430 All loaded catalogs will be used for message lookup by GetString() for
433 This overload takes two additional arguments, @a msgIdLanguage and @a msgIdCharset.
436 The catalog domain to add.
439 Specifies the language of "msgid" strings in source code
440 (i.e. arguments to GetString(), wxGetTranslation() and the _() macro).
441 It is used if AddCatalog() cannot find any catalog for current language:
442 if the language is same as source code language, then strings from source
443 code are used instead.
446 Lets you specify the charset used for msgids in sources
447 in case they use 8-bit characters (e.g. German or French strings).
448 This argument has no effect in Unicode build, because literals in sources are
449 Unicode strings; you have to use compiler-specific method of setting the right
450 charset when compiling with Unicode.
453 @true if catalog was successfully loaded, @false otherwise (which might
454 mean that the catalog is not found or that it isn't in the correct format).
456 bool AddCatalog(const wxString
& domain
, wxLanguage msgIdLanguage
,
457 const wxString
& msgIdCharset
);
460 Add a prefix to the catalog lookup path: the message catalog files will
461 be looked up under prefix/lang/LC_MESSAGES, prefix/lang and prefix
464 This only applies to subsequent invocations of AddCatalog().
466 static void AddCatalogLookupPathPrefix(const wxString
& prefix
);
469 Adds custom, user-defined language to the database of known languages.
470 This database is used in conjunction with the first form of Init().
472 static void AddLanguage(const wxLanguageInfo
& info
);
475 This function may be used to find the language description structure for the
476 given locale, specified either as a two letter ISO language code (for example,
477 "pt"), a language code followed by the country code ("pt_BR") or a full, human
478 readable, language description ("Portuguese-Brazil").
480 Returns the information for the given language or @NULL if this language
481 is unknown. Note that even if the returned pointer is valid, the caller
482 should @e not delete it.
484 @see GetLanguageInfo()
486 static const wxLanguageInfo
* FindLanguageInfo(const wxString
& locale
);
489 Returns the canonical form of current locale name. Canonical form is the
490 one that is used on UNIX systems: it is a two- or five-letter string in xx or
491 xx_YY format, where xx is ISO 639 code of language and YY is ISO 3166 code of
492 the country. Examples are "en", "en_GB", "en_US" or "fr_FR".
493 This form is internally used when looking up message catalogs.
494 Compare GetSysName().
496 wxString
GetCanonicalName() const;
499 Returns the header value for header @a header.
500 The search for @a header is case sensitive. If an @a domain is passed,
501 this domain is searched. Else all domains will be searched until a
502 header has been found.
504 The return value is the value of the header if found. Else this will be empty.
506 wxString
GetHeaderValue(const wxString
& header
,
507 const wxString
& domain
= wxEmptyString
) const;
510 Returns the ::wxLanguage constant of current language.
512 Note that you can call this function only if you used the form of
513 Init() that takes ::wxLanguage argument.
515 int GetLanguage() const;
518 Returns a pointer to wxLanguageInfo structure containing information about
519 the given language or @NULL if this language is unknown. Note that even if
520 the returned pointer is valid, the caller should @e not delete it.
522 See AddLanguage() for the wxLanguageInfo description.
523 As with Init(), @c wxLANGUAGE_DEFAULT has the special meaning if passed
524 as an argument to this function and in this case the result of
525 GetSystemLanguage() is used.
527 static const wxLanguageInfo
* GetLanguageInfo(int lang
);
530 Returns English name of the given language or empty string if this
533 See GetLanguageInfo() for a remark about special meaning of @c wxLANGUAGE_DEFAULT.
535 static wxString
GetLanguageName(int lang
);
538 Returns the locale name as passed to the constructor or Init().
540 This is a full, human-readable name, e.g. "English" or "French".
542 const wxString
& GetLocale() const;
545 Returns the current short name for the locale (as given to the constructor or
546 the Init() function).
548 const wxString
& GetName() const;
551 Retrieves the translation for a string in all loaded domains unless the @a domain
552 parameter is specified (and then only this catalog/domain is searched).
554 Returns original string if translation is not available (in this case an
555 error message is generated the first time a string is not found; use
556 wxLogNull to suppress it).
558 @remarks Domains are searched in the last to first order, i.e. catalogs
559 added later override those added before.
561 virtual const wxString
& GetString(const wxString
& origString
,
562 const wxString
& domain
= wxEmptyString
) const;
565 Retrieves the translation for a string in all loaded domains unless the @a domain
566 parameter is specified (and then only this catalog/domain is searched).
568 Returns original string if translation is not available (in this case an
569 error message is generated the first time a string is not found; use
570 wxLogNull to suppress it).
572 This form is used when retrieving translation of string that has different
573 singular and plural form in English or different plural forms in some
575 It takes two extra arguments: @a origString parameter must contain the
576 singular form of the string to be converted.
578 It is also used as the key for the search in the catalog.
579 The @a origString2 parameter is the plural form (in English).
581 The parameter @a n is used to determine the plural form.
582 If no message catalog is found @a origString is returned if 'n == 1',
583 otherwise @a origString2.
585 See GNU gettext manual for additional information on plural forms handling.
586 This method is called by the wxGetTranslation() function and _() macro.
588 @remarks Domains are searched in the last to first order, i.e. catalogs
589 added later override those added before.
591 virtual const wxString
& GetString(const wxString
& origString
,
592 const wxString
& origString2
, size_t n
,
593 const wxString
& domain
= wxEmptyString
) const;
596 Returns current platform-specific locale name as passed to setlocale().
597 Compare GetCanonicalName().
599 wxString
GetSysName() const;
602 Tries to detect the user's default font encoding.
603 Returns wxFontEncoding() value or @c wxFONTENCODING_SYSTEM if it
604 couldn't be determined.
606 static wxFontEncoding
GetSystemEncoding();
609 Tries to detect the name of the user's default font encoding.
610 This string isn't particularly useful for the application as its form is
611 platform-dependent and so you should probably use GetSystemEncoding() instead.
613 Returns a user-readable string value or an empty string if it couldn't be
616 static wxString
GetSystemEncodingName();
619 Tries to detect the user's default language setting.
620 Returns the ::wxLanguage value or @b wxLANGUAGE_UNKNOWN if the language-guessing
623 static int GetSystemLanguage();
626 Initializes the wxLocale instance.
628 The call of this function has several global side effects which you should
629 understand: first of all, the application locale is changed - note that
630 this will affect many of standard C library functions such as printf()
632 Second, this wxLocale object becomes the new current global locale for
633 the application and so all subsequent calls to wxGetTranslation() will
634 try to translate the messages using the message catalogs for this locale.
637 ::wxLanguage identifier of the locale.
638 @c wxLANGUAGE_DEFAULT has special meaning -- wxLocale will use system's
639 default language (see GetSystemLanguage()).
641 Combination of the following:
642 - wxLOCALE_LOAD_DEFAULT: Load the message catalog for the given locale
643 containing the translations of standard wxWidgets messages
645 - wxLOCALE_CONV_ENCODING: Automatically convert message catalogs to
646 platform's default encoding. Note that it will do only basic
647 conversion between well-known pair like iso8859-1 and windows-1252 or
648 iso8859-2 and windows-1250. See @ref overview_nonenglish for
649 detailed description of this behaviour.
650 Note that this flag is meaningless in Unicode build.
652 @return @true on success or @false if the given locale couldn't be set.
654 bool Init(int language
= wxLANGUAGE_DEFAULT
,
655 int flags
= wxLOCALE_LOAD_DEFAULT
| wxLOCALE_CONV_ENCODING
);
659 This form is deprecated, use the other one unless you know what you are doing.
662 The name of the locale. Only used in diagnostic messages.
664 The standard 2 letter locale abbreviation; it is used as the
665 directory prefix when looking for the message catalog files.
667 The parameter for the call to setlocale().
668 Note that it is platform-specific.
670 May be set to @false to prevent loading of the message catalog for the
671 given locale containing the translations of standard wxWidgets messages.
672 This parameter would be rarely used in normal circumstances.
673 @param bConvertEncoding
674 May be set to @true to do automatic conversion of message catalogs to
675 platform's native encoding. Note that it will do only basic conversion
676 between well-known pair like iso8859-1 and windows-1252 or iso8859-2
678 See @ref overview_nonenglish for detailed description of this behaviour.
680 bool Init(const wxString
& name
, const wxString
& short = wxEmptyString
,
681 const wxString
& locale
= wxEmptyString
, bool bLoadDefault
= true,
682 bool bConvertEncoding
= false);
685 Check whether the operating system and/or C run time environment supports
686 this locale. For example in Windows 2000 and Windows XP, support for many
687 locales is not installed by default. Returns @true if the locale is
690 The argument @a lang is the ::wxLanguage identifier. To obtain this for a
691 given a two letter ISO language code, use FindLanguageInfo() to obtain its
692 wxLanguageInfo structure.
693 See AddLanguage() for the wxLanguageInfo description.
697 static bool IsAvailable(int lang
);
700 Check if the given catalog is loaded, and returns @true if it is.
702 According to GNU gettext tradition, each catalog normally corresponds to
703 'domain' which is more or less the application name.
707 bool IsLoaded(const wxString
& domain
) const;
710 Returns @true if the locale could be set successfully.
718 // ============================================================================
719 // Global functions/macros
720 // ============================================================================
722 /** @addtogroup group_funcmacro_string */
726 This macro is identical to _() but for the plural variant of
729 @return A const wxString.
733 #define wxPLURAL(string, plural, n)
736 This macro doesn't do anything in the program code -- it simply expands to
737 the value of its argument.
739 However it does have a purpose which is to mark the literal strings for the
740 extraction into the message catalog created by @c xgettext program. Usually
741 this is achieved using _() but that macro not only marks the string for
742 extraction but also expands into a wxGetTranslation() call which means that
743 it cannot be used in some situations, notably for static array
746 Here is an example which should make it more clear: suppose that you have a
747 static array of strings containing the weekday names and which have to be
748 translated (note that it is a bad example, really, as wxDateTime already
749 can be used to get the localized week day names already). If you write:
752 static const char * const weekdays[] = { _("Mon"), ..., _("Sun") };
754 // use weekdays[n] as usual
757 The code wouldn't compile because the function calls are forbidden in the
758 array initializer. So instead you should do this:
761 static const char * const weekdays[] = { wxTRANSLATE("Mon"), ...,
762 wxTRANSLATE("Sun") };
764 // use wxGetTranslation(weekdays[n])
767 Note that although the code @b would compile if you simply omit
768 wxTRANSLATE() in the above, it wouldn't work as expected because there
769 would be no translations for the weekday names in the program message
770 catalog and wxGetTranslation() wouldn't find them.
772 @return A const wxChar*.
776 #define wxTRANSLATE(string)
779 This function returns the translation of @a string in the current
780 @c locale(). If the string is not found in any of the loaded message
781 catalogs (see @ref overview_i18n), the original string is returned. In
782 debug build, an error message is logged -- this should help to find the
783 strings which were not yet translated. If @a domain is specified then only
784 that domain/catalog is searched for a matching string. As this function is
785 used very often, an alternative (and also common in Unix world) syntax is
786 provided: the _() macro is defined to do the same thing as
789 This function calls wxLocale::GetString().
791 @note This function is not suitable for literal strings in Unicode builds
792 since the literal strings must be enclosed into _T() or wxT() macro
793 which makes them unrecognised by @c xgettext, and so they are not
794 extracted to the message catalog. Instead, use the _() and wxPLURAL()
795 macro for all literal strings.
797 @see wxGetTranslation(const wxString&, const wxString&, size_t, const wxString&)
801 const wxString
& wxGetTranslation(const wxString
& string
,
802 const wxString
& domain
= wxEmptyString
);
805 This is an overloaded version of
806 wxGetTranslation(const wxString&, const wxString&), please see its
807 documentation for general information.
809 This version is used when retrieving translation of string that has
810 different singular and plural forms in English or different plural forms in
811 some other language. Like wxGetTranslation(const wxString&,const wxString&),
812 the @a string parameter must contain the singular form of the string to be
813 converted and is used as the key for the search in the catalog. The
814 @a plural parameter is the plural form (in English). The parameter @a n is
815 used to determine the plural form. If no message catalog is found,
816 @a string is returned if "n == 1", otherwise @a plural is returned.
818 See GNU gettext Manual for additional information on plural forms handling:
819 <http://www.gnu.org/software/gettext/manual/gettext.html#Plural-forms>
820 For a shorter alternative see the wxPLURAL() macro.
822 This function calls wxLocale::GetString().
826 const wxString
& wxGetTranslation(const wxString
& string
,
827 const wxString
& plural
, size_t n
,
828 const wxString
& domain
= wxEmptyString
);
831 This macro expands into a call to wxGetTranslation(), so it marks the
832 message for the extraction by @c xgettext just as wxTRANSLATE() does, but
833 also returns the translation of the string for the current locale during
836 Don't confuse this with _T()!
840 const wxString
& _(const wxString
& string
);