interface/wx/translation.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        translation.h
   3 // Purpose:     wxTranslation class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   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
  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         Add standard wxWidgets catalogs ("wxstd" and possible port-specific
  84         catalogs).
  85
  86         @return @true if a suitable catalog was found, @false otherwise
  87
  88         @see AddCatalog()
  89      */
  90     bool AddStdCatalog();
  91
  92     /**
  93         Add a catalog for use with the current locale.
  94
  95         By default, it is searched for in standard places (see
  96         wxFileTranslationsLoader), but you may also prepend additional
  97         directories to the search path with
  98         wxFileTranslationsLoader::AddCatalogLookupPathPrefix().
  99
 100         All loaded catalogs will be used for message lookup by GetString() for
 101         the current locale.
 102
 103         In this overload, @c msgid strings are assumed
 104         to be in English and written only using 7-bit ASCII characters.
 105         If you have to deal with non-English strings or 8-bit characters in the
 106         source code, see the instructions in @ref overview_nonenglish.
 107
 108         @return
 109             @true if catalog was successfully loaded, @false otherwise (which might
 110             mean that the catalog is not found or that it isn't in the correct format).
 111      */
 112     bool AddCatalog(const wxString& domain);
 113
 114     /**
 115         Same as AddCatalog(const wxString&), but takes an additional argument,
 116         @a msgIdLanguage.
 117
 118         @param domain
 119             The catalog domain to add.
 120
 121         @param msgIdLanguage
 122             Specifies the language of "msgid" strings in source code
 123             (i.e. arguments to GetString(), wxGetTranslation() and the _() macro).
 124             It is used if AddCatalog() cannot find any catalog for current language:
 125             if the language is same as source code language, then strings from source
 126             code are used instead.
 127
 128         @return
 129             @true if catalog was successfully loaded, @false otherwise (which might
 130             mean that the catalog is not found or that it isn't in the correct format).
 131      */
 132     bool AddCatalog(const wxString& domain, wxLanguage msgIdLanguage);
 133
 134     /**
 135         Same as AddCatalog(const wxString&, wxLanguage), but takes two
 136         additional arguments, @a msgIdLanguage and @a msgIdCharset.
 137
 138         This overload is only available in non-Unicode build.
 139
 140         @param domain
 141             The catalog domain to add.
 142
 143         @param msgIdLanguage
 144             Specifies the language of "msgid" strings in source code
 145             (i.e. arguments to GetString(), wxGetTranslation() and the _() macro).
 146             It is used if AddCatalog() cannot find any catalog for current language:
 147             if the language is same as source code language, then strings from source
 148             code are used instead.
 149
 150         @param msgIdCharset
 151             Lets you specify the charset used for msgids in sources
 152             in case they use 8-bit characters (e.g. German or French strings).
 153
 154         @return
 155             @true if catalog was successfully loaded, @false otherwise (which might
 156             mean that the catalog is not found or that it isn't in the correct format).
 157      */
 158     bool AddCatalog(const wxString& domain,
 159                     wxLanguage msgIdLanguage,
 160                     const wxString& msgIdCharset);
 161
 162     /**
 163         Check if the given catalog is loaded, and returns @true if it is.
 164
 165         According to GNU gettext tradition, each catalog normally corresponds to
 166         'domain' which is more or less the application name.
 167
 168         @see AddCatalog()
 169      */
 170     bool IsLoaded(const wxString& domain) const;
 171
 172     /**
 173         Retrieves the translation for a string in all loaded domains unless the @a domain
 174         parameter is specified (and then only this catalog/domain is searched).
 175
 176         Returns original string if translation is not available (in this case an
 177         error message is generated the first time a string is not found; use
 178         wxLogNull to suppress it).
 179
 180         @remarks Domains are searched in the last to first order, i.e. catalogs
 181                  added later override those added before.
 182     */
 183     const wxString& GetString(const wxString& origString,
 184                               const wxString& domain = wxEmptyString) const;
 185
 186     /**
 187         Retrieves the translation for a string in all loaded domains unless the @a domain
 188         parameter is specified (and then only this catalog/domain is searched).
 189
 190         Returns original string if translation is not available (in this case an
 191         error message is generated the first time a string is not found; use
 192         wxLogNull to suppress it).
 193
 194         This form is used when retrieving translation of string that has different
 195         singular and plural form in English or different plural forms in some
 196         other language.
 197         It takes two extra arguments: @a origString parameter must contain the
 198         singular form of the string to be converted.
 199
 200         It is also used as the key for the search in the catalog.
 201         The @a origString2 parameter is the plural form (in English).
 202
 203         The parameter @a n is used to determine the plural form.
 204         If no message catalog is found @a origString is returned if 'n == 1',
 205         otherwise @a origString2.
 206
 207         See GNU gettext manual for additional information on plural forms handling.
 208         This method is called by the wxGetTranslation() function and _() macro.
 209
 210         @remarks Domains are searched in the last to first order, i.e. catalogs
 211                  added later override those added before.
 212     */
 213     const wxString& GetString(const wxString& origString,
 214                               const wxString& origString2,
 215                               unsigned n,
 216                               const wxString& domain = wxEmptyString) const;
 217
 218     /**
 219         Returns the header value for header @a header.
 220         The search for @a header is case sensitive. If an @a domain is passed,
 221         this domain is searched. Else all domains will be searched until a
 222         header has been found.
 223
 224         The return value is the value of the header if found. Else this will be empty.
 225     */
 226     wxString GetHeaderValue(const wxString& header,
 227                             const wxString& domain = wxEmptyString) const;
 228 };
 229
 230
 231 /**
 232     Abstraction of translations discovery and loading.
 233
 234     This interface makes it possible to override wxWidgets' default catalogs
 235     loading mechanism and load MO files from locations other than the
 236     filesystem (e.g. embed them in executable).
 237
 238     Implementations must implement the LoadCatalog() method.
 239
 240     @see wxFileTranslationsLoader, wxResourceTranslationsLoader
 241
 242     @since 2.9.1
 243  */
 244 class wxTranslationsLoader
 245 {
 246 public:
 247     /// Constructor
 248     wxTranslationsLoader() {}
 249
 250     /**
 251         Called to load requested catalog.
 252
 253         If the catalog is found, LoadCatalog() should create wxMsgCatalog
 254         instance with its data and return it. The caller will take ownership
 255         of the catalog.
 256
 257         @param domain        Domain to load.
 258         @param lang          Language to look for. This is "canonical name"
 259                              (see wxLocale::GetCanonicalName()), i.e. ISO 639
 260                              code, possibly combined with country code or
 261                              additional modifiers (e.g. "fr", "en_GB" or
 262                              "ca@valencia").
 263
 264         @return Loaded catalog or NULL on failure.
 265      */
 266     virtual wxMsgCatalog *LoadCatalog(const wxString& domain,
 267                                       const wxString& lang) = 0;
 268 };
 269
 270 /**
 271     Standard wxTranslationsLoader implementation.
 272
 273     This finds catalogs in the filesystem, using the standard Unix layout.
 274     This is the default unless you change the loader with
 275     wxTranslations::SetLoader().
 276
 277     Catalogs are searched for in standard places (current directory first, then
 278     the system one), but you may also prepend additional directories to the
 279     search path with AddCatalogLookupPathPrefix().
 280
 281     @since 2.9.1
 282  */
 283 class wxFileTranslationsLoader : public wxTranslationsLoader
 284 {
 285 public:
 286     /**
 287         Add a prefix to the catalog lookup path: the message catalog files will
 288         be looked up under prefix/lang/LC_MESSAGES, prefix/lang and prefix
 289         (in this order).
 290
 291         This only applies to subsequent invocations of
 292         wxTranslations::AddCatalog().
 293     */
 294     static void AddCatalogLookupPathPrefix(const wxString& prefix);
 295 };
 296
 297 /**
 298     This loader makes it possible to load translations from Windows
 299     resources.
 300
 301     If you wish to store translation MO files in resources, you have to
 302     enable this loader before calling wxTranslations::AddCatalog() or
 303     wxLocale::AddCatalog():
 304
 305     @code
 306     wxTranslations::Get()->SetLoader(new wxResourceTranslationsLoader);
 307     @endcode
 308
 309     Translations are stored in resources as compiled MO files, with type
 310     set to "MOFILE" (unless you override GetResourceType()) and name
 311     consisting of the domain, followed by underscore, followed by language
 312     identification. For example, the relevant part of .rc file would look
 313     like this:
 314
 315     @code
 316     myapp_de     MOFILE   "catalogs/de/myapp.mo"
 317     myapp_fr     MOFILE   "catalogs/fr/myapp.mo"
 318     myapp_en_GB  MOFILE   "catalogs/en_GB/myapp.mo"
 319     @endcode
 320
 321     This class is only available on Windows.
 322
 323     @since 2.9.1
 324  */
 325 class wxResourceTranslationsLoader : public wxTranslationsLoader
 326 {
 327 protected:
 328     /**
 329         Returns resource type to use for translations.
 330
 331         Default type is "MOFILE".
 332      */
 333     virtual wxString GetResourceType() const;
 334
 335     /**
 336         Returns handle of the module to load resources from.
 337
 338         By default, the main executable is used.
 339      */
 340     virtual WXHINSTANCE GetModule() const;
 341 };
 342
 343
 344 /**
 345     Represents a loaded translations message catalog.
 346
 347     This class should only be used directly by wxTranslationsLoader
 348     implementations.
 349
 350     @since 2.9.1
 351  */
 352 class wxMsgCatalog
 353 {
 354 public:
 355     /**
 356         Creates catalog loaded from a MO file.
 357
 358         @param filename  Path to the MO file to load.
 359         @param domain    Catalog's domain. This typically matches
 360                          the @a filename.
 361
 362         @return Successfully loaded catalog or NULL on failure.
 363      */
 364     static wxMsgCatalog *CreateFromFile(const wxString& filename,
 365                                         const wxString& domain);
 366
 367     /**
 368         Creates catalog from MO file data in memory buffer.
 369
 370         @param data      Data in MO file format.
 371         @param domain    Catalog's domain. This typically matches
 372                          the @a filename.
 373
 374         @return Successfully loaded catalog or NULL on failure.
 375      */
 376     static wxMsgCatalog *CreateFromData(const wxScopedCharBuffer& data,
 377                                         const wxString& domain);
 378 };
 379
 380
 381 // ============================================================================
 382 // Global functions/macros
 383 // ============================================================================
 384
 385 /** @addtogroup group_funcmacro_string */
 386 //@{
 387
 388 /**
 389     This macro is identical to _() but for the plural variant of
 390     wxGetTranslation().
 391
 392     @return A const wxString.
 393
 394     @header{wx/intl.h}
 395 */
 396 #define wxPLURAL(string, plural, n)
 397
 398 /**
 399     This macro doesn't do anything in the program code -- it simply expands to
 400     the value of its argument.
 401
 402     However it does have a purpose which is to mark the literal strings for the
 403     extraction into the message catalog created by @c xgettext program. Usually
 404     this is achieved using _() but that macro not only marks the string for
 405     extraction but also expands into a wxGetTranslation() call which means that
 406     it cannot be used in some situations, notably for static array
 407     initialization.
 408
 409     Here is an example which should make it more clear: suppose that you have a
 410     static array of strings containing the weekday names and which have to be
 411     translated (note that it is a bad example, really, as wxDateTime already
 412     can be used to get the localized week day names already). If you write:
 413
 414     @code
 415     static const char * const weekdays[] = { _("Mon"), ..., _("Sun") };
 416     ...
 417     // use weekdays[n] as usual
 418     @endcode
 419
 420     The code wouldn't compile because the function calls are forbidden in the
 421     array initializer. So instead you should do this:
 422
 423     @code
 424     static const char * const weekdays[] = { wxTRANSLATE("Mon"), ...,
 425     wxTRANSLATE("Sun") };
 426     ...
 427     // use wxGetTranslation(weekdays[n])
 428     @endcode
 429
 430     Note that although the code @b would compile if you simply omit
 431     wxTRANSLATE() in the above, it wouldn't work as expected because there
 432     would be no translations for the weekday names in the program message
 433     catalog and wxGetTranslation() wouldn't find them.
 434
 435     @return A const wxChar*.
 436
 437     @header{wx/intl.h}
 438 */
 439 #define wxTRANSLATE(string)
 440
 441 /**
 442     This function returns the translation of @a string in the current
 443     @c locale(). If the string is not found in any of the loaded message
 444     catalogs (see @ref overview_i18n), the original string is returned. In
 445     debug build, an error message is logged -- this should help to find the
 446     strings which were not yet translated.  If @a domain is specified then only
 447     that domain/catalog is searched for a matching string.  As this function is
 448     used very often, an alternative (and also common in Unix world) syntax is
 449     provided: the _() macro is defined to do the same thing as
 450     wxGetTranslation().
 451
 452     This function calls wxTranslations::GetString().
 453
 454     @note This function is not suitable for literal strings in Unicode builds
 455           since the literal strings must be enclosed into _T() or wxT() macro
 456           which makes them unrecognised by @c xgettext, and so they are not
 457           extracted to the message catalog. Instead, use the _() and wxPLURAL()
 458           macro for all literal strings.
 459
 460     @see wxGetTranslation(const wxString&, const wxString&, unsigned, const wxString&)
 461
 462     @header{wx/intl.h}
 463 */
 464 const wxString& wxGetTranslation(const wxString& string,
 465                                  const wxString& domain = wxEmptyString);
 466
 467 /**
 468     This is an overloaded version of
 469     wxGetTranslation(const wxString&, const wxString&), please see its
 470     documentation for general information.
 471
 472     This version is used when retrieving translation of string that has
 473     different singular and plural forms in English or different plural forms in
 474     some other language. Like wxGetTranslation(const wxString&,const wxString&),
 475     the @a string parameter must contain the singular form of the string to be
 476     converted and is used as the key for the search in the catalog. The
 477     @a plural parameter is the plural form (in English). The parameter @a n is
 478     used to determine the plural form. If no message catalog is found,
 479     @a string is returned if "n == 1", otherwise @a plural is returned.
 480
 481     See GNU gettext Manual for additional information on plural forms handling:
 482     <http://www.gnu.org/software/gettext/manual/gettext.html#Plural-forms>
 483     For a shorter alternative see the wxPLURAL() macro.
 484
 485     This function calls wxLocale::GetString().
 486
 487     @header{wx/intl.h}
 488 */
 489 const wxString& wxGetTranslation(const wxString& string,
 490                                  const wxString& plural, unsigned n,
 491                                  const wxString& domain = wxEmptyString);
 492
 493 /**
 494     This macro expands into a call to wxGetTranslation(), so it marks the
 495     message for the extraction by @c xgettext just as wxTRANSLATE() does, but
 496     also returns the translation of the string for the current locale during
 497     execution.
 498
 499     Don't confuse this with _T()!
 500
 501     @header{wx/intl.h}
 502 */
 503 const wxString& _(const wxString& string);
 504
 505 //@}
 506