interface/wx/translation.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        translation.h
   3 // Purpose:     wxTranslation class
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8
   9 /**
  10     This class allows to get translations for strings.
  11
  12     In wxWidgets this class manages message catalogs which contain the
  13     translations of the strings used to the current language. Unlike wxLocale,
  14     it isn't bound to locale. It can be used either independently of, or in
  15     conjunction with wxLocale. In the latter case, you should initialize
  16     wxLocale (which creates wxTranslations instance) first; in the former, you
  17     need to create a wxTranslations object and Set() it manually.
  18
  19     Only one wxTranslations instance is active at a time; it is set with the
  20     Set() method and obtained using Get().
  21
  22     Unlike wxLocale, wxTranslations' primary mean of identifying language
  23     is by its "canonical name", i.e. ISO 639 code, possibly combined with
  24     ISO 3166 country code and additional modifiers (examples include
  25     "fr", "en_GB" or "ca@valencia"; see wxLocale::GetCanonicalName() for
  26     more information). This allows apps using wxTranslations API to use even
  27     languages not recognized by the operating system or not listed in
  28     wxLanguage enum.
  29
  30     @since 2.9.1
  31
  32     @see wxLocale, wxTranslationsLoader, wxFileTranslationsLoader
  33  */
  34 class wxTranslations
  35 {
  36 public:
  37     /// Constructor
  38     wxTranslations();
  39
  40     /**
  41         Returns current translations object, may return NULL.
  42
  43         You must either call this early in app initialization code, or let
  44         wxLocale do it for you.
  45      */
  46     static wxTranslations *Get();
  47
  48     /**
  49         Sets current translations object.
  50
  51         Deletes previous translation object and takes ownership of @a t.
  52      */
  53     static void Set(wxTranslations *t);
  54
  55     /**
  56         Changes loader use to read catalogs to a non-default one.
  57
  58         Deletes previous loader and takes ownership of @a loader.
  59
  60         @see wxTranslationsLoader, wxFileTranslationsLoader, wxResourceTranslationsLoader
  61      */
  62     void SetLoader(wxTranslationsLoader *loader);
  63
  64     /**
  65         Sets translations language to use.
  66
  67         wxLANGUAGE_DEFAULT has special meaning: best suitable translation,
  68         given user's preference and available translations, will be used.
  69      */
  70     void SetLanguage(wxLanguage lang);
  71
  72     /**
  73         Sets translations language to use.
  74
  75         Empty @a lang string has the same meaning as wxLANGUAGE_DEFAULT in
  76         SetLanguage(wxLanguage): best suitable translation, given user's
  77         preference and available translations, will be used.
  78      */
  79     void SetLanguage(const wxString& lang);
  80
  81     /**
  82         Returns list of all translations of @a domain that were found.
  83
  84         This method can be used e.g. to populate list of application's
  85         translations offered to the user. To do this, pass the app's main
  86         catalog as @a domain.
  87
  88         @see GetBestTranslation()
  89      */
  90     wxArrayString GetAvailableTranslations(const wxString& domain) const;
  91
  92     /**
  93         Returns the best UI language for the @a domain.
  94
  95         The language is determined from the preferred UI language or languages
  96         list the user configured in the OS. Notice that this may or may not
  97         correspond to the default @em locale as obtained from
  98         wxLocale::GetSystemLanguage(); modern operation systems (Windows
  99         Vista+, OS X) have separate language and regional (= locale) settings.
 100
 101         @param domain
 102             The catalog domain to look for.
 103
 104         @param msgIdLanguage
 105             Specifies the language of "msgid" strings in source code
 106             (i.e. arguments to GetString(), wxGetTranslation() and the _() macro).
 107
 108         @return Language code if a suitable match was found, empty string
 109                 otherwise.
 110
 111         @since 2.9.5
 112      */
 113     wxString GetBestTranslation(const wxString& domain, wxLanguage msgIdLanguage);
 114
 115     /**
 116         Returns the best UI language for the @a domain.
 117
 118         The language is determined from the preferred UI language or languages
 119         list the user configured in the OS. Notice that this may or may not
 120         correspond to the default @em locale as obtained from
 121         wxLocale::GetSystemLanguage(); modern operation systems (Windows
 122         Vista+, OS X) have separate language and regional (= locale) settings.
 123
 124         @param domain
 125             The catalog domain to look for.
 126
 127         @param msgIdLanguage
 128             Specifies the language of "msgid" strings in source code
 129             (i.e. arguments to GetString(), wxGetTranslation() and the _() macro).
 130
 131         @return Language code if a suitable match was found, empty string
 132                 otherwise.
 133
 134         @since 2.9.5
 135      */
 136     wxString GetBestTranslation(const wxString& domain,
 137                                 const wxString& msgIdLanguage = "en");
 138
 139     /**
 140         Add standard wxWidgets catalogs ("wxstd" and possible port-specific
 141         catalogs).
 142
 143         @return @true if a suitable catalog was found, @false otherwise
 144
 145         @see AddCatalog()
 146      */
 147     bool AddStdCatalog();
 148
 149     /**
 150         Add a catalog for use with the current locale.
 151
 152         By default, it is searched for in standard places (see
 153         wxFileTranslationsLoader), but you may also prepend additional
 154         directories to the search path with
 155         wxFileTranslationsLoader::AddCatalogLookupPathPrefix().
 156
 157         All loaded catalogs will be used for message lookup by GetString() for
 158         the current locale.
 159
 160         In this overload, @c msgid strings are assumed
 161         to be in English and written only using 7-bit ASCII characters.
 162         If you have to deal with non-English strings or 8-bit characters in the
 163         source code, see the instructions in @ref overview_nonenglish.
 164
 165         @return
 166             @true if catalog was successfully loaded, @false otherwise (which might
 167             mean that the catalog is not found or that it isn't in the correct format).
 168      */
 169     bool AddCatalog(const wxString& domain);
 170
 171     /**
 172         Same as AddCatalog(const wxString&), but takes an additional argument,
 173         @a msgIdLanguage.
 174
 175         @param domain
 176             The catalog domain to add.
 177
 178         @param msgIdLanguage
 179             Specifies the language of "msgid" strings in source code
 180             (i.e. arguments to GetString(), wxGetTranslation() and the _() macro).
 181             It is used if AddCatalog() cannot find any catalog for current language:
 182             if the language is same as source code language, then strings from source
 183             code are used instead.
 184
 185         @return
 186             @true if catalog was successfully loaded, @false otherwise (which might
 187             mean that the catalog is not found or that it isn't in the correct format).
 188      */
 189     bool AddCatalog(const wxString& domain, wxLanguage msgIdLanguage);
 190
 191     /**
 192         Same as AddCatalog(const wxString&, wxLanguage), but takes two
 193         additional arguments, @a msgIdLanguage and @a msgIdCharset.
 194
 195         This overload is only available in non-Unicode build.
 196
 197         @param domain
 198             The catalog domain to add.
 199
 200         @param msgIdLanguage
 201             Specifies the language of "msgid" strings in source code
 202             (i.e. arguments to GetString(), wxGetTranslation() and the _() macro).
 203             It is used if AddCatalog() cannot find any catalog for current language:
 204             if the language is same as source code language, then strings from source
 205             code are used instead.
 206
 207         @param msgIdCharset
 208             Lets you specify the charset used for msgids in sources
 209             in case they use 8-bit characters (e.g. German or French strings).
 210
 211         @return
 212             @true if catalog was successfully loaded, @false otherwise (which might
 213             mean that the catalog is not found or that it isn't in the correct format).
 214      */
 215     bool AddCatalog(const wxString& domain,
 216                     wxLanguage msgIdLanguage,
 217                     const wxString& msgIdCharset);
 218
 219     /**
 220         Check if the given catalog is loaded, and returns @true if it is.
 221
 222         According to GNU gettext tradition, each catalog normally corresponds to
 223         'domain' which is more or less the application name.
 224
 225         @see AddCatalog()
 226      */
 227     bool IsLoaded(const wxString& domain) const;
 228
 229     /**
 230         Retrieves the translation for a string in all loaded domains unless the @a domain
 231         parameter is specified (and then only this catalog/domain is searched).
 232
 233         Returns @NULL if translation is not available.
 234
 235         This function is thread-safe.
 236
 237         @remarks Domains are searched in the last to first order, i.e. catalogs
 238                  added later override those added before.
 239
 240         @since 3.0
 241     */
 242     const wxString *GetTranslatedString(const wxString& origString,
 243                                         const wxString& domain = wxEmptyString) const;
 244
 245     /**
 246         Retrieves the translation for a string in all loaded domains unless the @a domain
 247         parameter is specified (and then only this catalog/domain is searched).
 248
 249         Returns @NULL if translation is not available.
 250
 251         This form is used when retrieving translation of string that has different
 252         singular and plural form in English or different plural forms in some
 253         other language.
 254
 255         @param origString  The singular form of the string to be converted.
 256         @param n           The number on which the plural form choice depends on.
 257                            (In some languages, there are different plural forms
 258                            for e.g. n=2 and n=3 etc., in addition to the singlular
 259                            form (n=1) being different.)
 260
 261         See GNU gettext manual for additional information on plural forms handling.
 262         This method is called by the wxGetTranslation() function and _() macro.
 263
 264         This function is thread-safe.
 265
 266         @remarks Domains are searched in the last to first order, i.e. catalogs
 267                  added later override those added before.
 268
 269         @since 3.0
 270     */
 271     const wxString *GetTranslatedString(const wxString& origString,
 272                                         unsigned n,
 273                                         const wxString& domain = wxEmptyString) const;
 274
 275     /**
 276         Returns the header value for header @a header.
 277         The search for @a header is case sensitive. If an @a domain is passed,
 278         this domain is searched. Else all domains will be searched until a
 279         header has been found.
 280
 281         The return value is the value of the header if found. Else this will be empty.
 282     */
 283     wxString GetHeaderValue(const wxString& header,
 284                             const wxString& domain = wxEmptyString) const;
 285 };
 286
 287
 288 /**
 289     Abstraction of translations discovery and loading.
 290
 291     This interface makes it possible to override wxWidgets' default catalogs
 292     loading mechanism and load MO files from locations other than the
 293     filesystem (e.g. embed them in executable).
 294
 295     Implementations must implement the LoadCatalog() method.
 296
 297     @see wxFileTranslationsLoader, wxResourceTranslationsLoader
 298
 299     @since 2.9.1
 300  */
 301 class wxTranslationsLoader
 302 {
 303 public:
 304     /// Trivial default constructor.
 305     wxTranslationsLoader();
 306
 307     /**
 308         Called to load requested catalog.
 309
 310         If the catalog is found, LoadCatalog() should create wxMsgCatalog
 311         instance with its data and return it. The caller will take ownership
 312         of the catalog.
 313
 314         @param domain        Domain to load.
 315         @param lang          Language to look for. This is "canonical name"
 316                              (see wxLocale::GetCanonicalName()), i.e. ISO 639
 317                              code, possibly combined with country code or
 318                              additional modifiers (e.g. "fr", "en_GB" or
 319                              "ca@valencia").
 320
 321         @return Loaded catalog or NULL on failure.
 322      */
 323     virtual wxMsgCatalog *LoadCatalog(const wxString& domain,
 324                                       const wxString& lang) = 0;
 325
 326     /**
 327         Implements wxTranslations::GetAvailableTranslations().
 328      */
 329     virtual wxArrayString GetAvailableTranslations(const wxString& domain) const = 0;
 330 };
 331
 332 /**
 333     Standard wxTranslationsLoader implementation.
 334
 335     This finds catalogs in the filesystem, using the standard Unix layout.
 336     This is the default unless you change the loader with
 337     wxTranslations::SetLoader().
 338
 339     Catalogs are searched for in standard places (system locales directory,
 340     `LC_PATH` on Unix systems, Resources subdirectory of the application bundle
 341     on OS X, executable's directory on Windows), but you may also prepend
 342     additional directories to the search path with
 343     AddCatalogLookupPathPrefix().
 344
 345     @since 2.9.1
 346  */
 347 class wxFileTranslationsLoader : public wxTranslationsLoader
 348 {
 349 public:
 350     /**
 351         Add a prefix to the catalog lookup path: the message catalog files will
 352         be looked up under prefix/lang/LC_MESSAGES and prefix/lang directories
 353         (in this order).
 354
 355         This only applies to subsequent invocations of
 356         wxTranslations::AddCatalog().
 357     */
 358     static void AddCatalogLookupPathPrefix(const wxString& prefix);
 359 };
 360
 361 /**
 362     This loader makes it possible to load translations from Windows
 363     resources.
 364
 365     If you wish to store translation MO files in resources, you have to
 366     enable this loader before calling wxTranslations::AddCatalog() or
 367     wxLocale::AddCatalog():
 368
 369     @code
 370     wxTranslations::Get()->SetLoader(new wxResourceTranslationsLoader);
 371     @endcode
 372
 373     Translations are stored in resources as compiled MO files, with type
 374     set to "MOFILE" (unless you override GetResourceType()) and name
 375     consisting of the domain, followed by underscore, followed by language
 376     identification. For example, the relevant part of .rc file would look
 377     like this:
 378
 379     @code
 380     myapp_de     MOFILE   "catalogs/de/myapp.mo"
 381     myapp_fr     MOFILE   "catalogs/fr/myapp.mo"
 382     myapp_en_GB  MOFILE   "catalogs/en_GB/myapp.mo"
 383     @endcode
 384
 385     This class is only available on Windows.
 386
 387     @since 2.9.1
 388  */
 389 class wxResourceTranslationsLoader : public wxTranslationsLoader
 390 {
 391 protected:
 392     /**
 393         Returns resource type to use for translations.
 394
 395         Default type is "MOFILE".
 396      */
 397     virtual wxString GetResourceType() const;
 398
 399     /**
 400         Returns handle of the module to load resources from.
 401
 402         By default, the main executable is used.
 403      */
 404     virtual WXHINSTANCE GetModule() const;
 405 };
 406
 407
 408 /**
 409     Represents a loaded translations message catalog.
 410
 411     This class should only be used directly by wxTranslationsLoader
 412     implementations.
 413
 414     @since 2.9.1
 415  */
 416 class wxMsgCatalog
 417 {
 418 public:
 419     /**
 420         Creates catalog loaded from a MO file.
 421
 422         @param filename  Path to the MO file to load.
 423         @param domain    Catalog's domain. This typically matches
 424                          the @a filename.
 425
 426         @return Successfully loaded catalog or NULL on failure.
 427      */
 428     static wxMsgCatalog *CreateFromFile(const wxString& filename,
 429                                         const wxString& domain);
 430
 431     /**
 432         Creates catalog from MO file data in memory buffer.
 433
 434         @param data      Data in MO file format.
 435         @param domain    Catalog's domain. This typically matches
 436                          the @a filename.
 437
 438         @return Successfully loaded catalog or NULL on failure.
 439      */
 440     static wxMsgCatalog *CreateFromData(const wxScopedCharBuffer& data,
 441                                         const wxString& domain);
 442 };
 443
 444
 445 // ============================================================================
 446 // Global functions/macros
 447 // ============================================================================
 448
 449 /** @addtogroup group_funcmacro_string */
 450 //@{
 451
 452 /**
 453     This macro is identical to _() but for the plural variant of
 454     wxGetTranslation().
 455
 456     @return A const wxString.
 457
 458     @header{wx/intl.h}
 459 */
 460 #define wxPLURAL(string, plural, n)
 461
 462 /**
 463     This macro doesn't do anything in the program code -- it simply expands to
 464     the value of its argument.
 465
 466     However it does have a purpose which is to mark the literal strings for the
 467     extraction into the message catalog created by @c xgettext program. Usually
 468     this is achieved using _() but that macro not only marks the string for
 469     extraction but also expands into a wxGetTranslation() call which means that
 470     it cannot be used in some situations, notably for static array
 471     initialization.
 472
 473     Here is an example which should make it more clear: suppose that you have a
 474     static array of strings containing the weekday names and which have to be
 475     translated (note that it is a bad example, really, as wxDateTime already
 476     can be used to get the localized week day names already). If you write:
 477
 478     @code
 479     static const char * const weekdays[] = { _("Mon"), ..., _("Sun") };
 480     ...
 481     // use weekdays[n] as usual
 482     @endcode
 483
 484     The code wouldn't compile because the function calls are forbidden in the
 485     array initializer. So instead you should do this:
 486
 487     @code
 488     static const char * const weekdays[] = { wxTRANSLATE("Mon"), ...,
 489     wxTRANSLATE("Sun") };
 490     ...
 491     // use wxGetTranslation(weekdays[n])
 492     @endcode
 493
 494     Note that although the code @b would compile if you simply omit
 495     wxTRANSLATE() in the above, it wouldn't work as expected because there
 496     would be no translations for the weekday names in the program message
 497     catalog and wxGetTranslation() wouldn't find them.
 498
 499     @return A const wxChar*.
 500
 501     @header{wx/intl.h}
 502 */
 503 #define wxTRANSLATE(string)
 504
 505 /**
 506     This function returns the translation of @a string in the current
 507     @c locale(). If the string is not found in any of the loaded message
 508     catalogs (see @ref overview_i18n), the original string is returned. In
 509     debug build, an error message is logged -- this should help to find the
 510     strings which were not yet translated.  If @a domain is specified then only
 511     that domain/catalog is searched for a matching string.  As this function is
 512     used very often, an alternative (and also common in Unix world) syntax is
 513     provided: the _() macro is defined to do the same thing as
 514     wxGetTranslation().
 515
 516     This function is thread-safe.
 517
 518     @note This function is not suitable for literal strings in Unicode builds
 519           since the literal strings must be enclosed in wxT() macro which makes
 520           them unrecognised by @c xgettext, and so they are not extracted to
 521           the message catalog. Instead, use the _() and wxPLURAL() macro for
 522           all literal strings.
 523
 524     @see wxGetTranslation(const wxString&, const wxString&, unsigned, const wxString&)
 525
 526     @header{wx/intl.h}
 527 */
 528 const wxString& wxGetTranslation(const wxString& string,
 529                                  const wxString& domain = wxEmptyString);
 530
 531 /**
 532     This is an overloaded version of
 533     wxGetTranslation(const wxString&, const wxString&), please see its
 534     documentation for general information.
 535
 536     This version is used when retrieving translation of string that has
 537     different singular and plural forms in English or different plural forms in
 538     some other language. Like wxGetTranslation(const wxString&,const wxString&),
 539     the @a string parameter must contain the singular form of the string to be
 540     converted and is used as the key for the search in the catalog. The
 541     @a plural parameter is the plural form (in English). The parameter @a n is
 542     used to determine the plural form. If no message catalog is found,
 543     @a string is returned if "n == 1", otherwise @a plural is returned.
 544
 545     See GNU gettext Manual for additional information on plural forms handling:
 546     <http://www.gnu.org/software/gettext/manual/gettext.html#Plural-forms>
 547     For a shorter alternative see the wxPLURAL() macro.
 548
 549     This function is thread-safe.
 550
 551     @header{wx/intl.h}
 552 */
 553 const wxString& wxGetTranslation(const wxString& string,
 554                                  const wxString& plural, unsigned n,
 555                                  const wxString& domain = wxEmptyString);
 556
 557 /**
 558     Macro to be used around all literal strings that should be translated.
 559
 560     This macro expands into a call to wxGetTranslation(), so it marks the
 561     message for the extraction by @c xgettext just as wxTRANSLATE() does, but
 562     also returns the translation of the string for the current locale during
 563     execution.
 564
 565     This macro is thread-safe.
 566
 567     @header{wx/intl.h}
 568 */
 569 const wxString& _(const wxString& string);
 570
 571 //@}
 572