interface/intl.h

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