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