interface/wx/translation.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        translation.h
   3 // Purpose:     wxTranslation class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  11     This class allows to get translations for strings.
  12
  13     In wxWidgets this class manages message catalogs which contain the
  14     translations of the strings used to the current language. Unlike wxLocale,
  15     it isn't bound to locale. It can be used either independently of, or in
  16     conjunction with wxLocale. In the latter case, you should initialize
  17     wxLocale (which creates wxTranslations instance) first; in the former, you
  18     need to create a wxTranslations object and Set() it manually.
  19
  20     Only one wxTranslations instance is active at a time; it is set with the
  21     Set() method and obtained using Get().
  22
  23     Unlike wxLocale, wxTranslations' primary mean of identifying language
  24     is by its "canonical name", i.e. ISO 639 code, possibly combined with
  25     ISO 3166 country code and additional modifiers (examples include
  26     "fr", "en_GB" or "ca@valencia"; see wxLocale::GetCanonicalName() for
  27     more information). This allows apps using wxTranslations API to use even
  28     languages not recognized by the operating system or not listed in
  29     wxLanguage enum.
  30
  31     @since 2.9.1
  32
  33     @see wxLocale, wxTranslationsLoader, wxFileTranslationsLoader
  34  */
  35 class wxTranslations
  36 {
  37 public:
  38     /// Constructor
  39     wxTranslations();
  40
  41     /**
  42         Returns current translations object, may return NULL.
  43
  44         You must either call this early in app initialization code, or let
  45         wxLocale do it for you.
  46      */
  47     static wxTranslations *Get();
  48
  49     /**
  50         Sets current translations object.
  51
  52         Deletes previous translation object and takes ownership of @a t.
  53      */
  54     static void Set(wxTranslations *t);
  55
  56     /**
  57         Changes loader use to read catalogs to a non-default one.
  58
  59         Deletes previous loader and takes ownership of @a loader.
  60
  61         @see wxTranslationsLoader, wxFileTranslationsLoader, wxResourceTranslationsLoader
  62      */
  63     void SetLoader(wxTranslationsLoader *loader);
  64
  65     /**
  66         Sets translations language to use.
  67
  68         wxLANGUAGE_DEFAULT has special meaning: best suitable translation,
  69         given user's preference and available translations, will be used.
  70      */
  71     void SetLanguage(wxLanguage lang);
  72
  73     /**
  74         Sets translations language to use.
  75
  76         Empty @a lang string has the same meaning as wxLANGUAGE_DEFAULT in
  77         SetLanguage(wxLanguage): best suitable translation, given user's
  78         preference and available translations, will be used.
  79      */
  80     void SetLanguage(const wxString& lang);
  81
  82     /**
  83         Returns list of all translations of @a domain that were found.
  84
  85         This method can be used e.g. to populate list of application's
  86         translations offered to the user. To do this, pass the app's main
  87         catalog as @a domain.
  88
  89         @see GetBestTranslation()
  90      */
  91     wxArrayString GetAvailableTranslations(const wxString& domain) const;
  92
  93     /**
  94         Returns the best UI language for the @a domain.
  95
  96         The language is determined from the preferred UI language or languages
  97         list the user configured in the OS. Notice that this may or may not
  98         correspond to the default @em locale as obtained from
  99         wxLocale::GetSystemLanguage(); modern operation systems (Windows
 100         Vista+, OS X) have separate language and regional (= locale) settings.
 101
 102         @param domain
 103             The catalog domain to look for.
 104
 105         @param msgIdLanguage
 106             Specifies the language of "msgid" strings in source code
 107             (i.e. arguments to GetString(), wxGetTranslation() and the _() macro).
 108
 109         @return Language code if a suitable match was found, empty string
 110                 otherwise.
 111
 112         @since 2.9.5
 113      */
 114     wxString GetBestTranslation(const wxString& domain, wxLanguage msgIdLanguage);
 115
 116     /**
 117         Returns the best UI language for the @a domain.
 118
 119         The language is determined from the preferred UI language or languages
 120         list the user configured in the OS. Notice that this may or may not
 121         correspond to the default @em locale as obtained from
 122         wxLocale::GetSystemLanguage(); modern operation systems (Windows
 123         Vista+, OS X) have separate language and regional (= locale) settings.
 124
 125         @param domain
 126             The catalog domain to look for.
 127
 128         @param msgIdLanguage
 129             Specifies the language of "msgid" strings in source code
 130             (i.e. arguments to GetString(), wxGetTranslation() and the _() macro).
 131
 132         @return Language code if a suitable match was found, empty string
 133                 otherwise.
 134
 135         @since 2.9.5
 136      */
 137     wxString GetBestTranslation(const wxString& domain,
 138                                 const wxString& msgIdLanguage = "en");
 139
 140     /**
 141         Add standard wxWidgets catalogs ("wxstd" and possible port-specific
 142         catalogs).
 143
 144         @return @true if a suitable catalog was found, @false otherwise
 145
 146         @see AddCatalog()
 147      */
 148     bool AddStdCatalog();
 149
 150     /**
 151         Add a catalog for use with the current locale.
 152
 153         By default, it is searched for in standard places (see
 154         wxFileTranslationsLoader), but you may also prepend additional
 155         directories to the search path with
 156         wxFileTranslationsLoader::AddCatalogLookupPathPrefix().
 157
 158         All loaded catalogs will be used for message lookup by GetString() for
 159         the current locale.
 160
 161         In this overload, @c msgid strings are assumed
 162         to be in English and written only using 7-bit ASCII characters.
 163         If you have to deal with non-English strings or 8-bit characters in the
 164         source code, see the instructions in @ref overview_nonenglish.
 165
 166         @return
 167             @true if catalog was successfully loaded, @false otherwise (which might
 168             mean that the catalog is not found or that it isn't in the correct format).
 169      */
 170     bool AddCatalog(const wxString& domain);
 171
 172     /**
 173         Same as AddCatalog(const wxString&), but takes an additional argument,
 174         @a msgIdLanguage.
 175
 176         @param domain
 177             The catalog domain to add.
 178
 179         @param msgIdLanguage
 180             Specifies the language of "msgid" strings in source code
 181             (i.e. arguments to GetString(), wxGetTranslation() and the _() macro).
 182             It is used if AddCatalog() cannot find any catalog for current language:
 183             if the language is same as source code language, then strings from source
 184             code are used instead.
 185
 186         @return
 187             @true if catalog was successfully loaded, @false otherwise (which might
 188             mean that the catalog is not found or that it isn't in the correct format).
 189      */
 190     bool AddCatalog(const wxString& domain, wxLanguage msgIdLanguage);
 191
 192     /**
 193         Same as AddCatalog(const wxString&, wxLanguage), but takes two
 194         additional arguments, @a msgIdLanguage and @a msgIdCharset.
 195
 196         This overload is only available in non-Unicode build.
 197
 198         @param domain
 199             The catalog domain to add.
 200
 201         @param msgIdLanguage
 202             Specifies the language of "msgid" strings in source code
 203             (i.e. arguments to GetString(), wxGetTranslation() and the _() macro).
 204             It is used if AddCatalog() cannot find any catalog for current language:
 205             if the language is same as source code language, then strings from source
 206             code are used instead.
 207
 208         @param msgIdCharset
 209             Lets you specify the charset used for msgids in sources
 210             in case they use 8-bit characters (e.g. German or French strings).
 211
 212         @return
 213             @true if catalog was successfully loaded, @false otherwise (which might
 214             mean that the catalog is not found or that it isn't in the correct format).
 215      */
 216     bool AddCatalog(const wxString& domain,
 217                     wxLanguage msgIdLanguage,
 218                     const wxString& msgIdCharset);
 219
 220     /**
 221         Check if the given catalog is loaded, and returns @true if it is.
 222
 223         According to GNU gettext tradition, each catalog normally corresponds to
 224         'domain' which is more or less the application name.
 225
 226         @see AddCatalog()
 227      */
 228     bool IsLoaded(const wxString& domain) const;
 229
 230     /**
 231         Retrieves the translation for a string in all loaded domains unless the @a domain
 232         parameter is specified (and then only this catalog/domain is searched).
 233
 234         Returns original string if translation is not available (in this case an
 235         error message is generated the first time a string is not found; use
 236         wxLogNull to suppress it).
 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
 244     /**
 245         Retrieves the translation for a string in all loaded domains unless the @a domain
 246         parameter is specified (and then only this catalog/domain is searched).
 247
 248         Returns original string if translation is not available (in this case an
 249         error message is generated the first time a string is not found; use
 250         wxLogNull to suppress it).
 251
 252         This form is used when retrieving translation of string that has different
 253         singular and plural form in English or different plural forms in some
 254         other language.
 255         It takes two extra arguments: @a origString parameter must contain the
 256         singular form of the string to be converted.
 257
 258         It is also used as the key for the search in the catalog.
 259         The @a origString2 parameter is the plural form (in English).
 260
 261         The parameter @a n is used to determine the plural form.
 262         If no message catalog is found @a origString is returned if 'n == 1',
 263         otherwise @a origString2.
 264
 265         See GNU gettext manual for additional information on plural forms handling.
 266         This method is called by the wxGetTranslation() function and _() macro.
 267
 268         @remarks Domains are searched in the last to first order, i.e. catalogs
 269                  added later override those added before.
 270     */
 271     const wxString& GetString(const wxString& origString,
 272                               const wxString& origString2,
 273                               unsigned n,
 274                               const wxString& domain = wxEmptyString) const;
 275
 276     /**
 277         Returns the header value for header @a header.
 278         The search for @a header is case sensitive. If an @a domain is passed,
 279         this domain is searched. Else all domains will be searched until a
 280         header has been found.
 281
 282         The return value is the value of the header if found. Else this will be empty.
 283     */
 284     wxString GetHeaderValue(const wxString& header,
 285                             const wxString& domain = wxEmptyString) const;
 286 };
 287
 288
 289 /**
 290     Abstraction of translations discovery and loading.
 291
 292     This interface makes it possible to override wxWidgets' default catalogs
 293     loading mechanism and load MO files from locations other than the
 294     filesystem (e.g. embed them in executable).
 295
 296     Implementations must implement the LoadCatalog() method.
 297
 298     @see wxFileTranslationsLoader, wxResourceTranslationsLoader
 299
 300     @since 2.9.1
 301  */
 302 class wxTranslationsLoader
 303 {
 304 public:
 305     /// Trivial default constructor.
 306     wxTranslationsLoader();
 307
 308     /**
 309         Called to load requested catalog.
 310
 311         If the catalog is found, LoadCatalog() should create wxMsgCatalog
 312         instance with its data and return it. The caller will take ownership
 313         of the catalog.
 314
 315         @param domain        Domain to load.
 316         @param lang          Language to look for. This is "canonical name"
 317                              (see wxLocale::GetCanonicalName()), i.e. ISO 639
 318                              code, possibly combined with country code or
 319                              additional modifiers (e.g. "fr", "en_GB" or
 320                              "ca@valencia").
 321
 322         @return Loaded catalog or NULL on failure.
 323      */
 324     virtual wxMsgCatalog *LoadCatalog(const wxString& domain,
 325                                       const wxString& lang) = 0;
 326
 327     /**
 328         Implements wxTranslations::GetAvailableTranslations().
 329      */
 330     virtual wxArrayString GetAvailableTranslations(const wxString& domain) const = 0;
 331 };
 332
 333 /**
 334     Standard wxTranslationsLoader implementation.
 335
 336     This finds catalogs in the filesystem, using the standard Unix layout.
 337     This is the default unless you change the loader with
 338     wxTranslations::SetLoader().
 339
 340     Catalogs are searched for in standard places (system locales directory,
 341     `LC_PATH` on Unix systems, Resources folder on OS X, executable's directory
 342     on Windows), but you may also prepend additional directories to the search
 343     path with 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, prefix/lang and prefix
 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 calls wxTranslations::GetString().
 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 calls wxLocale::GetString().
 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     @header{wx/intl.h}
 566 */
 567 const wxString& _(const wxString& string);
 568
 569 //@}
 570