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