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