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