interface/wx/intl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        intl.h
   3 // Purpose:     interface of wxLocale
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 // --- --- --- generated code begins here --- --- ---
  11
  12 /**
  13     The languages supported by wxLocale.
  14
  15     This enum is generated by misc/languages/genlang.py
  16     When making changes, please put them into misc/languages/langtabl.txt
  17 */
  18 enum wxLanguage
  19 {
  20     /// User's default/preffered language as got from OS.
  21     wxLANGUAGE_DEFAULT,
  22
  23     /// Unknown language, returned if wxLocale::GetSystemLanguage fails.
  24     wxLANGUAGE_UNKNOWN,
  25
  26     wxLANGUAGE_ABKHAZIAN,
  27     wxLANGUAGE_AFAR,
  28     wxLANGUAGE_AFRIKAANS,
  29     wxLANGUAGE_ALBANIAN,
  30     wxLANGUAGE_AMHARIC,
  31     wxLANGUAGE_ARABIC,
  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,
  49     wxLANGUAGE_ARMENIAN,
  50     wxLANGUAGE_ASSAMESE,
  51     wxLANGUAGE_AYMARA,
  52     wxLANGUAGE_AZERI,
  53     wxLANGUAGE_AZERI_CYRILLIC,
  54     wxLANGUAGE_AZERI_LATIN,
  55     wxLANGUAGE_BASHKIR,
  56     wxLANGUAGE_BASQUE,
  57     wxLANGUAGE_BELARUSIAN,
  58     wxLANGUAGE_BENGALI,
  59     wxLANGUAGE_BHUTANI,
  60     wxLANGUAGE_BIHARI,
  61     wxLANGUAGE_BISLAMA,
  62     wxLANGUAGE_BRETON,
  63     wxLANGUAGE_BULGARIAN,
  64     wxLANGUAGE_BURMESE,
  65     wxLANGUAGE_CAMBODIAN,
  66     wxLANGUAGE_CATALAN,
  67     wxLANGUAGE_CHINESE,
  68     wxLANGUAGE_CHINESE_SIMPLIFIED,
  69     wxLANGUAGE_CHINESE_TRADITIONAL,
  70     wxLANGUAGE_CHINESE_HONGKONG,
  71     wxLANGUAGE_CHINESE_MACAU,
  72     wxLANGUAGE_CHINESE_SINGAPORE,
  73     wxLANGUAGE_CHINESE_TAIWAN,
  74     wxLANGUAGE_CORSICAN,
  75     wxLANGUAGE_CROATIAN,
  76     wxLANGUAGE_CZECH,
  77     wxLANGUAGE_DANISH,
  78     wxLANGUAGE_DUTCH,
  79     wxLANGUAGE_DUTCH_BELGIAN,
  80     wxLANGUAGE_ENGLISH,
  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,
  96     wxLANGUAGE_ESPERANTO,
  97     wxLANGUAGE_ESTONIAN,
  98     wxLANGUAGE_FAEROESE,
  99     wxLANGUAGE_FARSI,
 100     wxLANGUAGE_FIJI,
 101     wxLANGUAGE_FINNISH,
 102     wxLANGUAGE_FRENCH,
 103     wxLANGUAGE_FRENCH_BELGIAN,
 104     wxLANGUAGE_FRENCH_CANADIAN,
 105     wxLANGUAGE_FRENCH_LUXEMBOURG,
 106     wxLANGUAGE_FRENCH_MONACO,
 107     wxLANGUAGE_FRENCH_SWISS,
 108     wxLANGUAGE_FRISIAN,
 109     wxLANGUAGE_GALICIAN,
 110     wxLANGUAGE_GEORGIAN,
 111     wxLANGUAGE_GERMAN,
 112     wxLANGUAGE_GERMAN_AUSTRIAN,
 113     wxLANGUAGE_GERMAN_BELGIUM,
 114     wxLANGUAGE_GERMAN_LIECHTENSTEIN,
 115     wxLANGUAGE_GERMAN_LUXEMBOURG,
 116     wxLANGUAGE_GERMAN_SWISS,
 117     wxLANGUAGE_GREEK,
 118     wxLANGUAGE_GREENLANDIC,
 119     wxLANGUAGE_GUARANI,
 120     wxLANGUAGE_GUJARATI,
 121     wxLANGUAGE_HAUSA,
 122     wxLANGUAGE_HEBREW,
 123     wxLANGUAGE_HINDI,
 124     wxLANGUAGE_HUNGARIAN,
 125     wxLANGUAGE_ICELANDIC,
 126     wxLANGUAGE_INDONESIAN,
 127     wxLANGUAGE_INTERLINGUA,
 128     wxLANGUAGE_INTERLINGUE,
 129     wxLANGUAGE_INUKTITUT,
 130     wxLANGUAGE_INUPIAK,
 131     wxLANGUAGE_IRISH,
 132     wxLANGUAGE_ITALIAN,
 133     wxLANGUAGE_ITALIAN_SWISS,
 134     wxLANGUAGE_JAPANESE,
 135     wxLANGUAGE_JAVANESE,
 136     wxLANGUAGE_KANNADA,
 137     wxLANGUAGE_KASHMIRI,
 138     wxLANGUAGE_KASHMIRI_INDIA,
 139     wxLANGUAGE_KAZAKH,
 140     wxLANGUAGE_KERNEWEK,
 141     wxLANGUAGE_KINYARWANDA,
 142     wxLANGUAGE_KIRGHIZ,
 143     wxLANGUAGE_KIRUNDI,
 144     wxLANGUAGE_KONKANI,
 145     wxLANGUAGE_KOREAN,
 146     wxLANGUAGE_KURDISH,
 147     wxLANGUAGE_LAOTHIAN,
 148     wxLANGUAGE_LATIN,
 149     wxLANGUAGE_LATVIAN,
 150     wxLANGUAGE_LINGALA,
 151     wxLANGUAGE_LITHUANIAN,
 152     wxLANGUAGE_MACEDONIAN,
 153     wxLANGUAGE_MALAGASY,
 154     wxLANGUAGE_MALAY,
 155     wxLANGUAGE_MALAYALAM,
 156     wxLANGUAGE_MALAY_BRUNEI_DARUSSALAM,
 157     wxLANGUAGE_MALAY_MALAYSIA,
 158     wxLANGUAGE_MALTESE,
 159     wxLANGUAGE_MANIPURI,
 160     wxLANGUAGE_MAORI,
 161     wxLANGUAGE_MARATHI,
 162     wxLANGUAGE_MOLDAVIAN,
 163     wxLANGUAGE_MONGOLIAN,
 164     wxLANGUAGE_NAURU,
 165     wxLANGUAGE_NEPALI,
 166     wxLANGUAGE_NEPALI_INDIA,
 167     wxLANGUAGE_NORWEGIAN_BOKMAL,
 168     wxLANGUAGE_NORWEGIAN_NYNORSK,
 169     wxLANGUAGE_OCCITAN,
 170     wxLANGUAGE_ORIYA,
 171     wxLANGUAGE_OROMO,
 172     wxLANGUAGE_PASHTO,
 173     wxLANGUAGE_POLISH,
 174     wxLANGUAGE_PORTUGUESE,
 175     wxLANGUAGE_PORTUGUESE_BRAZILIAN,
 176     wxLANGUAGE_PUNJABI,
 177     wxLANGUAGE_QUECHUA,
 178     wxLANGUAGE_RHAETO_ROMANCE,
 179     wxLANGUAGE_ROMANIAN,
 180     wxLANGUAGE_RUSSIAN,
 181     wxLANGUAGE_RUSSIAN_UKRAINE,
 182     wxLANGUAGE_SAMI,
 183     wxLANGUAGE_SAMOAN,
 184     wxLANGUAGE_SANGHO,
 185     wxLANGUAGE_SANSKRIT,
 186     wxLANGUAGE_SCOTS_GAELIC,
 187     wxLANGUAGE_SERBIAN,
 188     wxLANGUAGE_SERBIAN_CYRILLIC,
 189     wxLANGUAGE_SERBIAN_LATIN,
 190     wxLANGUAGE_SERBO_CROATIAN,
 191     wxLANGUAGE_SESOTHO,
 192     wxLANGUAGE_SETSWANA,
 193     wxLANGUAGE_SHONA,
 194     wxLANGUAGE_SINDHI,
 195     wxLANGUAGE_SINHALESE,
 196     wxLANGUAGE_SISWATI,
 197     wxLANGUAGE_SLOVAK,
 198     wxLANGUAGE_SLOVENIAN,
 199     wxLANGUAGE_SOMALI,
 200     wxLANGUAGE_SPANISH,
 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,
 222     wxLANGUAGE_SWAHILI,
 223     wxLANGUAGE_SWEDISH,
 224     wxLANGUAGE_SWEDISH_FINLAND,
 225     wxLANGUAGE_TAGALOG,
 226     wxLANGUAGE_TAJIK,
 227     wxLANGUAGE_TAMIL,
 228     wxLANGUAGE_TATAR,
 229     wxLANGUAGE_TELUGU,
 230     wxLANGUAGE_THAI,
 231     wxLANGUAGE_TIBETAN,
 232     wxLANGUAGE_TIGRINYA,
 233     wxLANGUAGE_TONGA,
 234     wxLANGUAGE_TSONGA,
 235     wxLANGUAGE_TURKISH,
 236     wxLANGUAGE_TURKMEN,
 237     wxLANGUAGE_TWI,
 238     wxLANGUAGE_UIGHUR,
 239     wxLANGUAGE_UKRAINIAN,
 240     wxLANGUAGE_URDU,
 241     wxLANGUAGE_URDU_INDIA,
 242     wxLANGUAGE_URDU_PAKISTAN,
 243     wxLANGUAGE_UZBEK,
 244     wxLANGUAGE_UZBEK_CYRILLIC,
 245     wxLANGUAGE_UZBEK_LATIN,
 246     wxLANGUAGE_VALENCIAN,
 247     wxLANGUAGE_VIETNAMESE,
 248     wxLANGUAGE_VOLAPUK,
 249     wxLANGUAGE_WELSH,
 250     wxLANGUAGE_WOLOF,
 251     wxLANGUAGE_XHOSA,
 252     wxLANGUAGE_YIDDISH,
 253     wxLANGUAGE_YORUBA,
 254     wxLANGUAGE_ZHUANG,
 255     wxLANGUAGE_ZULU,
 256
 257     /// For custom, user-defined languages.
 258     wxLANGUAGE_USER_DEFINED
 259 };
 260
 261 // --- --- --- generated code ends here --- --- ---
 262
 263
 264
 265 /**
 266     wxLanguageInfo: encapsulates ::wxLanguage to OS native lang.desc.
 267                     translation information
 268 */
 269 struct WXDLLIMPEXP_BASE wxLanguageInfo
 270 {
 271     /// ::wxLanguage id. It should be greater than wxLANGUAGE_USER_DEFINED.
 272     int Language;
 273     wxString CanonicalName;         //!< Canonical name, e.g. fr_FR.
 274 #ifdef __WXMSW__
 275     wxUint32 WinLang,               //!< Win32 language identifiers (LANG_xxxx, SUBLANG_xxxx).
 276              WinSublang;
 277 #endif // __WXMSW__
 278     wxString Description;           //!< Human-readable name of the language.
 279     wxLayoutDirection LayoutDirection;
 280
 281 #ifdef __WXMSW__
 282     /// Return the LCID corresponding to this language.
 283     wxUint32 GetLCID() const;
 284 #endif // __WXMSW__
 285
 286     /// Return the locale name corresponding to this language usable with
 287     /// setlocale() on the current system
 288     wxString GetLocaleName() const;
 289 };
 290
 291
 292 /**
 293     @class wxLocale
 294
 295     wxLocale class encapsulates all language-dependent settings and is a
 296     generalization of the C locale concept.
 297
 298     In wxWidgets this class manages message catalogs which contain the translations
 299     of the strings used to the current language.
 300
 301     For a list of the supported languages, please see ::wxLanguage enum values.
 302     These constants may be used to specify the language in wxLocale::Init and
 303     are returned by wxLocale::GetSystemLanguage.
 304
 305     @beginWxPerlOnly
 306     In wxPerl you can't use the '_' function name, so
 307     the @c Wx::Locale module can export the @c gettext and
 308     @c gettext_noop under any given name.
 309
 310     @code
 311       # this imports gettext ( equivalent to Wx::GetTranslation
 312       # and gettext_noop ( a noop )
 313       # into your module
 314       use Wx::Locale qw(:default);
 315
 316       # ....
 317
 318       # use the functions
 319       print gettext( "Panic!" );
 320
 321       button = Wx::Button-new( window, -1, gettext( "Label" ) );
 322     @endcode
 323
 324     If you need to translate a lot of strings, then adding gettext( ) around
 325     each one is a long task ( that is why _( ) was introduced ), so just choose
 326     a shorter name for gettext:
 327
 328     @code
 329       use Wx::Locale 'gettext' = 't',
 330                      'gettext_noop' = 'gettext_noop';
 331
 332       # ...
 333
 334       # use the functions
 335       print t( "Panic!!" );
 336
 337       # ...
 338     @endcode
 339     @endWxPerlOnly
 340
 341     @library{wxbase}
 342     @category{misc}
 343
 344     @see @ref overview_i18n, @ref page_samples_internat, wxXLocale
 345 */
 346 class wxLocale
 347 {
 348 public:
 349     /**
 350         This is the default constructor and it does nothing to initialize the object:
 351         Init() must be used to do that.
 352     */
 353     wxLocale();
 354
 355     /**
 356         See Init() for parameters description.
 357     */
 358     wxLocale(int language,
 359              int flags = wxLOCALE_LOAD_DEFAULT | wxLOCALE_CONV_ENCODING);
 360
 361     /**
 362         See Init() for parameters description.
 363
 364         The call of this function has several global side effects which you should
 365         understand: first of all, the application locale is changed - note that this
 366         will affect many of standard C library functions such as printf() or strftime().
 367         Second, this wxLocale object becomes the new current global locale for the
 368         application and so all subsequent calls to ::wxGetTranslation() will try to
 369         translate the messages using the message catalogs for this locale.
 370     */
 371     wxLocale(const wxString& name,
 372              const wxString& short = wxEmptyString,
 373              const wxString& locale = wxEmptyString,
 374              bool bLoadDefault = true,
 375              bool bConvertEncoding = false);
 376
 377     /**
 378         The destructor, like the constructor, also has global side effects: the
 379         previously set locale is restored and so the changes described in
 380         Init() documentation are rolled back.
 381     */
 382     virtual ~wxLocale();
 383
 384     /**
 385         Add a catalog for use with the current locale: it is searched for in standard
 386         places (current directory first, then the system one), but you may also prepend
 387         additional directories to the search path with AddCatalogLookupPathPrefix().
 388
 389         All loaded catalogs will be used for message lookup by GetString() for
 390         the current locale.
 391
 392         In this overload, @c msgid strings are assumed
 393         to be in English and written only using 7-bit ASCII characters.
 394         If you have to deal with non-English strings or 8-bit characters in the
 395         source code, see the instructions in @ref overview_nonenglish.
 396
 397         @return
 398             @true if catalog was successfully loaded, @false otherwise (which might
 399             mean that the catalog is not found or that it isn't in the correct format).
 400     */
 401     bool AddCatalog(const wxString& domain);
 402
 403     /**
 404         Add a catalog for use with the current locale: it is searched for in standard
 405         places (current directory first, then the system one), but you may also prepend
 406         additional directories to the search path with AddCatalogLookupPathPrefix().
 407
 408         All loaded catalogs will be used for message lookup by GetString() for
 409         the current locale.
 410
 411         This overload takes two additional arguments, @a msgIdLanguage and @a msgIdCharset.
 412
 413         @param domain
 414             The catalog domain to add.
 415
 416         @param msgIdLanguage
 417             Specifies the language of "msgid" strings in source code
 418             (i.e. arguments to GetString(), wxGetTranslation() and the _() macro).
 419             It is used if AddCatalog() cannot find any catalog for current language:
 420             if the language is same as source code language, then strings from source
 421             code are used instead.
 422
 423         @param msgIdCharset
 424             Lets you specify the charset used for msgids in sources
 425             in case they use 8-bit characters (e.g. German or French strings).
 426             This argument has no effect in Unicode build, because literals in sources are
 427             Unicode strings; you have to use compiler-specific method of setting the right
 428             charset when compiling with Unicode.
 429
 430         @return
 431             @true if catalog was successfully loaded, @false otherwise (which might
 432             mean that the catalog is not found or that it isn't in the correct format).
 433     */
 434     bool AddCatalog(const wxString& domain, wxLanguage msgIdLanguage,
 435                     const wxString& msgIdCharset);
 436
 437     /**
 438         Add a prefix to the catalog lookup path: the message catalog files will
 439         be looked up under prefix/lang/LC_MESSAGES, prefix/lang and prefix
 440         (in this order).
 441
 442         This only applies to subsequent invocations of AddCatalog().
 443     */
 444     static void AddCatalogLookupPathPrefix(const wxString& prefix);
 445
 446     /**
 447         Adds custom, user-defined language to the database of known languages.
 448         This database is used in conjunction with the first form of Init().
 449     */
 450     static void AddLanguage(const wxLanguageInfo& info);
 451
 452     /**
 453         This function may be used to find the language description structure for the
 454         given locale, specified either as a two letter ISO language code (for example,
 455         "pt"), a language code followed by the country code ("pt_BR") or a full, human
 456         readable, language description ("Portuguese-Brazil").
 457
 458         Returns the information for the given language or @NULL if this language
 459         is unknown. Note that even if the returned pointer is valid, the caller
 460         should @e not delete it.
 461
 462         @see GetLanguageInfo()
 463     */
 464     static wxLanguageInfo* FindLanguageInfo(const wxString& locale);
 465
 466     /**
 467         Returns the canonical form of current locale name. Canonical form is the
 468         one that is used on UNIX systems: it is a two- or five-letter string in xx or
 469         xx_YY format, where xx is ISO 639 code of language and YY is ISO 3166 code of
 470         the country. Examples are "en", "en_GB", "en_US" or "fr_FR".
 471         This form is internally used when looking up message catalogs.
 472         Compare GetSysName().
 473     */
 474     wxString GetCanonicalName() const;
 475
 476     /**
 477         Returns the header value for header @a header.
 478         The search for @a header is case sensitive. If an @a domain is passed,
 479         this domain is searched. Else all domains will be searched until a
 480         header has been found.
 481
 482         The return value is the value of the header if found. Else this will be empty.
 483     */
 484     wxString GetHeaderValue(const wxString& header,
 485                             const wxString& domain = wxEmptyString) const;
 486
 487     /**
 488         Returns the ::wxLanguage constant of current language.
 489
 490         Note that you can call this function only if you used the form of
 491         Init() that takes ::wxLanguage argument.
 492     */
 493     int GetLanguage() const;
 494
 495     /**
 496         Returns a pointer to wxLanguageInfo structure containing information about
 497         the given language or @NULL if this language is unknown. Note that even if
 498         the returned pointer is valid, the caller should @e not delete it.
 499
 500         See AddLanguage() for the wxLanguageInfo description.
 501         As with Init(), @c wxLANGUAGE_DEFAULT has the special meaning if passed
 502         as an argument to this function and in this case the result of
 503         GetSystemLanguage() is used.
 504     */
 505     static wxLanguageInfo* GetLanguageInfo(int lang) const;
 506
 507     /**
 508         Returns English name of the given language or empty string if this
 509         language is unknown.
 510
 511         See GetLanguageInfo() for a remark about special meaning of @c wxLANGUAGE_DEFAULT.
 512     */
 513     static wxString GetLanguageName(int lang) const;
 514
 515     /**
 516         Returns the locale name as passed to the constructor or Init().
 517
 518         This is a full, human-readable name, e.g. "English" or "French".
 519     */
 520     const wxString& GetLocale() const;
 521
 522     /**
 523         Returns the current short name for the locale (as given to the constructor or
 524         the Init() function).
 525     */
 526     const wxString& GetName() const;
 527
 528     /**
 529         Retrieves the translation for a string in all loaded domains unless the @a domain
 530         parameter is specified (and then only this catalog/domain is searched).
 531
 532         Returns original string if translation is not available (in this case an
 533         error message is generated the first time a string is not found; use
 534         wxLogNull to suppress it).
 535
 536         @remarks Domains are searched in the last to first order, i.e. catalogs
 537                  added later override those added before.
 538     */
 539     virtual const wxString& GetString(const wxString& origString,
 540                                       const wxString& domain = wxEmptyString) const;
 541
 542     /**
 543         Retrieves the translation for a string in all loaded domains unless the @a domain
 544         parameter is specified (and then only this catalog/domain is searched).
 545
 546         Returns original string if translation is not available (in this case an
 547         error message is generated the first time a string is not found; use
 548         wxLogNull to suppress it).
 549
 550         This form is used when retrieving translation of string that has different
 551         singular and plural form in English or different plural forms in some
 552         other language.
 553         It takes two extra arguments: @a origString parameter must contain the
 554         singular form of the string to be converted.
 555
 556         It is also used as the key for the search in the catalog.
 557         The @a origString2 parameter is the plural form (in English).
 558
 559         The parameter @a n is used to determine the plural form.
 560         If no message catalog is found @a origString is returned if 'n == 1',
 561         otherwise @a origString2.
 562
 563         See GNU gettext manual for additional information on plural forms handling.
 564         This method is called by the wxGetTranslation() function and _() macro.
 565
 566         @remarks Domains are searched in the last to first order, i.e. catalogs
 567                  added later override those added before.
 568     */
 569     virtual const wxString& GetString(const wxString& origString,
 570                                       const wxString& origString2, size_t n,
 571                                       const wxString& domain = wxEmptyString) const;
 572
 573     /**
 574         Returns current platform-specific locale name as passed to setlocale().
 575         Compare GetCanonicalName().
 576     */
 577     wxString GetSysName() const;
 578
 579     /**
 580         Tries to detect the user's default font encoding.
 581         Returns wxFontEncoding() value or @c wxFONTENCODING_SYSTEM if it
 582         couldn't be determined.
 583     */
 584     static wxFontEncoding GetSystemEncoding() const;
 585
 586     /**
 587         Tries to detect the name of the user's default font encoding.
 588         This string isn't particularly useful for the application as its form is
 589         platform-dependent and so you should probably use GetSystemEncoding() instead.
 590
 591         Returns a user-readable string value or an empty string if it couldn't be
 592         determined.
 593     */
 594     static wxString GetSystemEncodingName() const;
 595
 596     /**
 597         Tries to detect the user's default language setting.
 598         Returns the ::wxLanguage value or @b wxLANGUAGE_UNKNOWN if the language-guessing
 599         algorithm failed.
 600     */
 601     static int GetSystemLanguage() const;
 602
 603     /**
 604         Initializes the wxLocale instance.
 605
 606         The call of this function has several global side effects which you should
 607         understand: first of all, the application locale is changed - note that
 608         this will affect many of standard C library functions such as printf()
 609         or strftime().
 610         Second, this wxLocale object becomes the new current global locale for
 611         the application and so all subsequent calls to wxGetTranslation() will
 612         try to translate the messages using the message catalogs for this locale.
 613
 614         @param language
 615             ::wxLanguage identifier of the locale.
 616             @c wxLANGUAGE_DEFAULT has special meaning -- wxLocale will use system's
 617             default language (see GetSystemLanguage()).
 618         @param flags
 619             Combination of the following:
 620             - wxLOCALE_LOAD_DEFAULT: Load the message catalog for the given locale
 621               containing the translations of standard wxWidgets messages
 622               automatically.
 623             - wxLOCALE_CONV_ENCODING: Automatically convert message catalogs to
 624               platform's default encoding. Note that it will do only basic
 625               conversion between well-known pair like iso8859-1 and windows-1252 or
 626               iso8859-2 and windows-1250. See @ref overview_nonenglish for
 627               detailed description of this behaviour.
 628               Note that this flag is meaningless in Unicode build.
 629
 630         @return @true on success or @false if the given locale couldn't be set.
 631     */
 632     bool Init(int language = wxLANGUAGE_DEFAULT,
 633               int flags = wxLOCALE_LOAD_DEFAULT | wxLOCALE_CONV_ENCODING);
 634
 635     /**
 636         @deprecated
 637         This form is deprecated, use the other one unless you know what you are doing.
 638
 639         @param name
 640             The name of the locale. Only used in diagnostic messages.
 641         @param short
 642             The standard 2 letter locale abbreviation; it is used as the
 643             directory prefix when looking for the message catalog files.
 644         @param locale
 645             The parameter for the call to setlocale().
 646             Note that it is platform-specific.
 647         @param bLoadDefault
 648             May be set to @false to prevent loading of the message catalog for the
 649             given locale containing the translations of standard wxWidgets messages.
 650             This parameter would be rarely used in normal circumstances.
 651         @param bConvertEncoding
 652             May be set to @true to do automatic conversion of message catalogs to
 653             platform's native encoding. Note that it will do only basic conversion
 654             between well-known pair like iso8859-1 and windows-1252 or iso8859-2
 655             and windows-1250.
 656             See @ref overview_nonenglish for detailed description of this behaviour.
 657     */
 658     bool Init(const wxString& name, const wxString& short = wxEmptyString,
 659               const wxString& locale = wxEmptyString, bool bLoadDefault = true,
 660               bool bConvertEncoding = false);
 661
 662     /**
 663         Check whether the operating system and/or C run time environment supports
 664         this locale. For example in Windows 2000 and Windows XP, support for many
 665         locales is not installed by default. Returns @true if the locale is
 666         supported.
 667
 668         The argument @a lang is the ::wxLanguage identifier. To obtain this for a
 669         given a two letter ISO language code, use FindLanguageInfo() to obtain its
 670         wxLanguageInfo structure.
 671         See AddLanguage() for the wxLanguageInfo description.
 672
 673         @since 2.7.1.
 674     */
 675     static bool IsAvailable(int lang);
 676
 677     /**
 678         Check if the given catalog is loaded, and returns @true if it is.
 679
 680         According to GNU gettext tradition, each catalog normally corresponds to
 681         'domain' which is more or less the application name.
 682
 683         @see AddCatalog()
 684     */
 685     bool IsLoaded(const wxString& domain) const;
 686
 687     /**
 688         Returns @true if the locale could be set successfully.
 689     */
 690     bool IsOk() const;
 691 };
 692
 693
 694
 695
 696 // ============================================================================
 697 // Global functions/macros
 698 // ============================================================================
 699
 700 /** @ingroup group_funcmacro_string */
 701 //@{
 702
 703 /**
 704     This macro is identical to _() but for the plural variant of
 705     wxGetTranslation().
 706
 707     @return A const wxString.
 708
 709     @header{wx/intl.h}
 710 */
 711 #define wxPLURAL(string, plural, n)
 712
 713 /**
 714     This macro doesn't do anything in the program code -- it simply expands to
 715     the value of its argument.
 716
 717     However it does have a purpose which is to mark the literal strings for the
 718     extraction into the message catalog created by @c xgettext program. Usually
 719     this is achieved using _() but that macro not only marks the string for
 720     extraction but also expands into a wxGetTranslation() call which means that
 721     it cannot be used in some situations, notably for static array
 722     initialization.
 723
 724     Here is an example which should make it more clear: suppose that you have a
 725     static array of strings containing the weekday names and which have to be
 726     translated (note that it is a bad example, really, as wxDateTime already
 727     can be used to get the localized week day names already). If you write:
 728
 729     @code
 730     static const char * const weekdays[] = { _("Mon"), ..., _("Sun") };
 731     ...
 732     // use weekdays[n] as usual
 733     @endcode
 734
 735     The code wouldn't compile because the function calls are forbidden in the
 736     array initializer. So instead you should do this:
 737
 738     @code
 739     static const char * const weekdays[] = { wxTRANSLATE("Mon"), ...,
 740     wxTRANSLATE("Sun") };
 741     ...
 742     // use wxGetTranslation(weekdays[n])
 743     @endcode
 744
 745     Note that although the code @b would compile if you simply omit
 746     wxTRANSLATE() in the above, it wouldn't work as expected because there
 747     would be no translations for the weekday names in the program message
 748     catalog and wxGetTranslation() wouldn't find them.
 749
 750     @return A const wxChar*.
 751
 752     @header{wx/intl.h}
 753 */
 754 #define wxTRANSLATE(string)
 755
 756 /**
 757     This function returns the translation of @a string in the current
 758     @c locale(). If the string is not found in any of the loaded message
 759     catalogs (see @ref overview_i18n), the original string is returned. In
 760     debug build, an error message is logged -- this should help to find the
 761     strings which were not yet translated.  If @a domain is specified then only
 762     that domain/catalog is searched for a matching string.  As this function is
 763     used very often, an alternative (and also common in Unix world) syntax is
 764     provided: the _() macro is defined to do the same thing as
 765     wxGetTranslation().
 766
 767     This function calls wxLocale::GetString().
 768
 769     @note This function is not suitable for literal strings in Unicode builds
 770           since the literal strings must be enclosed into _T() or wxT() macro
 771           which makes them unrecognised by @c xgettext, and so they are not
 772           extracted to the message catalog. Instead, use the _() and wxPLURAL()
 773           macro for all literal strings.
 774
 775     @see wxGetTranslation(const wxString&, const wxString&, size_t, const wxString&)
 776
 777     @header{wx/intl.h}
 778 */
 779 const wxString& wxGetTranslation(const wxString& string,
 780                                  const wxString& domain = wxEmptyString);
 781
 782 /**
 783     This is an overloaded version of
 784     wxGetTranslation(const wxString&, const wxString&), please see its
 785     documentation for general information.
 786
 787     This version is used when retrieving translation of string that has
 788     different singular and plural forms in English or different plural forms in
 789     some other language. Like wxGetTranslation(const wxString&,const wxString&),
 790     the @a string parameter must contain the singular form of the string to be
 791     converted and is used as the key for the search in the catalog. The
 792     @a plural parameter is the plural form (in English). The parameter @a n is
 793     used to determine the plural form. If no message catalog is found,
 794     @a string is returned if "n == 1", otherwise @a plural is returned.
 795
 796     See GNU gettext Manual for additional information on plural forms handling:
 797     <http://www.gnu.org/software/gettext/manual/gettext.html#Plural-forms>
 798     For a shorter alternative see the wxPLURAL() macro.
 799
 800     This function calls wxLocale::GetString().
 801
 802     @header{wx/intl.h}
 803 */
 804 const wxString& wxGetTranslation(const wxString& string,
 805                                  const wxString& plural, size_t n,
 806                                  const wxString& domain = wxEmptyString);
 807
 808 /**
 809     This macro expands into a call to wxGetTranslation(), so it marks the
 810     message for the extraction by @c xgettext just as wxTRANSLATE() does, but
 811     also returns the translation of the string for the current locale during
 812     execution.
 813
 814     Don't confuse this with _T()!
 815
 816     @header{wx/intl.h}
 817 */
 818 const wxString& _(const wxString& string);
 819
 820 //@}
 821