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 subdirectory of the application bundle
 342     on OS X, executable's directory on Windows), but you may also prepend
 343     additional directories to the search path with
 344     AddCatalogLookupPathPrefix().
 345
 346     @since 2.9.1
 347  */
 348 class wxFileTranslationsLoader : public wxTranslationsLoader
 349 {
 350 public:
 351     /**
 352         Add a prefix to the catalog lookup path: the message catalog files will
 353         be looked up under prefix/lang/LC_MESSAGES and prefix/lang directories
 354         (in this order).
 355
 356         This only applies to subsequent invocations of
 357         wxTranslations::AddCatalog().
 358     */
 359     static void AddCatalogLookupPathPrefix(const wxString& prefix);
 360 };
 361
 362 /**
 363     This loader makes it possible to load translations from Windows
 364     resources.
 365
 366     If you wish to store translation MO files in resources, you have to
 367     enable this loader before calling wxTranslations::AddCatalog() or
 368     wxLocale::AddCatalog():
 369
 370     @code
 371     wxTranslations::Get()->SetLoader(new wxResourceTranslationsLoader);
 372     @endcode
 373
 374     Translations are stored in resources as compiled MO files, with type
 375     set to "MOFILE" (unless you override GetResourceType()) and name
 376     consisting of the domain, followed by underscore, followed by language
 377     identification. For example, the relevant part of .rc file would look
 378     like this:
 379
 380     @code
 381     myapp_de     MOFILE   "catalogs/de/myapp.mo"
 382     myapp_fr     MOFILE   "catalogs/fr/myapp.mo"
 383     myapp_en_GB  MOFILE   "catalogs/en_GB/myapp.mo"
 384     @endcode
 385
 386     This class is only available on Windows.
 387
 388     @since 2.9.1
 389  */
 390 class wxResourceTranslationsLoader : public wxTranslationsLoader
 391 {
 392 protected:
 393     /**
 394         Returns resource type to use for translations.
 395
 396         Default type is "MOFILE".
 397      */
 398     virtual wxString GetResourceType() const;
 399
 400     /**
 401         Returns handle of the module to load resources from.
 402
 403         By default, the main executable is used.
 404      */
 405     virtual WXHINSTANCE GetModule() const;
 406 };
 407
 408
 409 /**
 410     Represents a loaded translations message catalog.
 411
 412     This class should only be used directly by wxTranslationsLoader
 413     implementations.
 414
 415     @since 2.9.1
 416  */
 417 class wxMsgCatalog
 418 {
 419 public:
 420     /**
 421         Creates catalog loaded from a MO file.
 422
 423         @param filename  Path to the MO file to load.
 424         @param domain    Catalog's domain. This typically matches
 425                          the @a filename.
 426
 427         @return Successfully loaded catalog or NULL on failure.
 428      */
 429     static wxMsgCatalog *CreateFromFile(const wxString& filename,
 430                                         const wxString& domain);
 431
 432     /**
 433         Creates catalog from MO file data in memory buffer.
 434
 435         @param data      Data in MO file format.
 436         @param domain    Catalog's domain. This typically matches
 437                          the @a filename.
 438
 439         @return Successfully loaded catalog or NULL on failure.
 440      */
 441     static wxMsgCatalog *CreateFromData(const wxScopedCharBuffer& data,
 442                                         const wxString& domain);
 443 };
 444
 445
 446 // ============================================================================
 447 // Global functions/macros
 448 // ============================================================================
 449
 450 /** @addtogroup group_funcmacro_string */
 451 //@{
 452
 453 /**
 454     This macro is identical to _() but for the plural variant of
 455     wxGetTranslation().
 456
 457     @return A const wxString.
 458
 459     @header{wx/intl.h}
 460 */
 461 #define wxPLURAL(string, plural, n)
 462
 463 /**
 464     This macro doesn't do anything in the program code -- it simply expands to
 465     the value of its argument.
 466
 467     However it does have a purpose which is to mark the literal strings for the
 468     extraction into the message catalog created by @c xgettext program. Usually
 469     this is achieved using _() but that macro not only marks the string for
 470     extraction but also expands into a wxGetTranslation() call which means that
 471     it cannot be used in some situations, notably for static array
 472     initialization.
 473
 474     Here is an example which should make it more clear: suppose that you have a
 475     static array of strings containing the weekday names and which have to be
 476     translated (note that it is a bad example, really, as wxDateTime already
 477     can be used to get the localized week day names already). If you write:
 478
 479     @code
 480     static const char * const weekdays[] = { _("Mon"), ..., _("Sun") };
 481     ...
 482     // use weekdays[n] as usual
 483     @endcode
 484
 485     The code wouldn't compile because the function calls are forbidden in the
 486     array initializer. So instead you should do this:
 487
 488     @code
 489     static const char * const weekdays[] = { wxTRANSLATE("Mon"), ...,
 490     wxTRANSLATE("Sun") };
 491     ...
 492     // use wxGetTranslation(weekdays[n])
 493     @endcode
 494
 495     Note that although the code @b would compile if you simply omit
 496     wxTRANSLATE() in the above, it wouldn't work as expected because there
 497     would be no translations for the weekday names in the program message
 498     catalog and wxGetTranslation() wouldn't find them.
 499
 500     @return A const wxChar*.
 501
 502     @header{wx/intl.h}
 503 */
 504 #define wxTRANSLATE(string)
 505
 506 /**
 507     This function returns the translation of @a string in the current
 508     @c locale(). If the string is not found in any of the loaded message
 509     catalogs (see @ref overview_i18n), the original string is returned. In
 510     debug build, an error message is logged -- this should help to find the
 511     strings which were not yet translated.  If @a domain is specified then only
 512     that domain/catalog is searched for a matching string.  As this function is
 513     used very often, an alternative (and also common in Unix world) syntax is
 514     provided: the _() macro is defined to do the same thing as
 515     wxGetTranslation().
 516
 517     This function calls wxTranslations::GetString().
 518
 519     @note This function is not suitable for literal strings in Unicode builds
 520           since the literal strings must be enclosed in wxT() macro which makes
 521           them unrecognised by @c xgettext, and so they are not extracted to
 522           the message catalog. Instead, use the _() and wxPLURAL() macro for
 523           all literal strings.
 524
 525     @see wxGetTranslation(const wxString&, const wxString&, unsigned, const wxString&)
 526
 527     @header{wx/intl.h}
 528 */
 529 const wxString& wxGetTranslation(const wxString& string,
 530                                  const wxString& domain = wxEmptyString);
 531
 532 /**
 533     This is an overloaded version of
 534     wxGetTranslation(const wxString&, const wxString&), please see its
 535     documentation for general information.
 536
 537     This version is used when retrieving translation of string that has
 538     different singular and plural forms in English or different plural forms in
 539     some other language. Like wxGetTranslation(const wxString&,const wxString&),
 540     the @a string parameter must contain the singular form of the string to be
 541     converted and is used as the key for the search in the catalog. The
 542     @a plural parameter is the plural form (in English). The parameter @a n is
 543     used to determine the plural form. If no message catalog is found,
 544     @a string is returned if "n == 1", otherwise @a plural is returned.
 545
 546     See GNU gettext Manual for additional information on plural forms handling:
 547     <http://www.gnu.org/software/gettext/manual/gettext.html#Plural-forms>
 548     For a shorter alternative see the wxPLURAL() macro.
 549
 550     This function calls wxLocale::GetString().
 551
 552     @header{wx/intl.h}
 553 */
 554 const wxString& wxGetTranslation(const wxString& string,
 555                                  const wxString& plural, unsigned n,
 556                                  const wxString& domain = wxEmptyString);
 557
 558 /**
 559     Macro to be used around all literal strings that should be translated.
 560
 561     This macro expands into a call to wxGetTranslation(), so it marks the
 562     message for the extraction by @c xgettext just as wxTRANSLATE() does, but
 563     also returns the translation of the string for the current locale during
 564     execution.
 565
 566     @header{wx/intl.h}
 567 */
 568 const wxString& _(const wxString& string);
 569
 570 //@}
 571