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         Directly loads catalog from a file.
 174
 175         It is caller's responsibility to ensure that the catalog contains
 176         correct language. This function is primarily intended for
 177         wxTranslationsLoader implementations.
 178
 179         @param filename  Name of the MO file to load.
 180         @param domain    Domain to load the translations into (typically
 181                          matches file's basename).
 182      */
 183     bool LoadCatalogFile(const wxString& filename,
 184                          const wxString& domain = wxEmptyString);
 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         @remarks Domains are searched in the last to first order, i.e. catalogs
 195                  added later override those added before.
 196     */
 197     const wxString& GetString(const wxString& origString,
 198                               const wxString& domain = wxEmptyString) const;
 199
 200     /**
 201         Retrieves the translation for a string in all loaded domains unless the @a domain
 202         parameter is specified (and then only this catalog/domain is searched).
 203
 204         Returns original string if translation is not available (in this case an
 205         error message is generated the first time a string is not found; use
 206         wxLogNull to suppress it).
 207
 208         This form is used when retrieving translation of string that has different
 209         singular and plural form in English or different plural forms in some
 210         other language.
 211         It takes two extra arguments: @a origString parameter must contain the
 212         singular form of the string to be converted.
 213
 214         It is also used as the key for the search in the catalog.
 215         The @a origString2 parameter is the plural form (in English).
 216
 217         The parameter @a n is used to determine the plural form.
 218         If no message catalog is found @a origString is returned if 'n == 1',
 219         otherwise @a origString2.
 220
 221         See GNU gettext manual for additional information on plural forms handling.
 222         This method is called by the wxGetTranslation() function and _() macro.
 223
 224         @remarks Domains are searched in the last to first order, i.e. catalogs
 225                  added later override those added before.
 226     */
 227     const wxString& GetString(const wxString& origString,
 228                               const wxString& origString2,
 229                               size_t n,
 230                               const wxString& domain = wxEmptyString) const;
 231
 232     /**
 233         Returns the header value for header @a header.
 234         The search for @a header is case sensitive. If an @a domain is passed,
 235         this domain is searched. Else all domains will be searched until a
 236         header has been found.
 237
 238         The return value is the value of the header if found. Else this will be empty.
 239     */
 240     wxString GetHeaderValue(const wxString& header,
 241                             const wxString& domain = wxEmptyString) const;
 242 };
 243
 244
 245 /**
 246     Abstraction of translations discovery and loading.
 247
 248     This interface makes it possible to override wxWidgets' default catalogs
 249     loading mechanism and load MO files from locations other than the
 250     filesystem (e.g. embed them in executable).
 251
 252     Implementations must implement the LoadCatalog() method.
 253
 254     @see wxFileTranslationsLoader, wxResourceTranslationsLoader
 255
 256     @since 2.9.1
 257  */
 258 class wxTranslationsLoader
 259 {
 260 public:
 261     /// Constructor
 262     wxTranslationsLoader() {}
 263
 264     /**
 265         Called to load requested catalog.
 266
 267         If the catalog is found, LoadCatalog() should call LoadCatalogFile()
 268         on @a translations to add the translation.
 269
 270         @param translations  wxTranslations requesting loading.
 271         @param domain        Domain to load.
 272         @param lang          Language to look for. This is "canonical name"
 273                              (see wxLocale::GetCanonicalName()), i.e. ISO 639
 274                              code, possibly combined with country code or
 275                              additional modifiers (e.g. "fr", "en_GB" or
 276                              "ca@valencia").
 277
 278         @return @true on successful load, @false otherwise
 279      */
 280     virtual bool LoadCatalog(wxTranslations *translations,
 281                              const wxString& domain, const wxString& lang) = 0;
 282 };
 283
 284 /**
 285     Standard wxTranslationsLoader implementation.
 286
 287     This finds catalogs in the filesystem, using the standard Unix layout.
 288     This is the default unless you change the loader with
 289     wxTranslations::SetLoader().
 290
 291     Catalogs are searched for in standard places (current directory first, then
 292     the system one), but you may also prepend additional directories to the
 293     search path with AddCatalogLookupPathPrefix().
 294
 295     @since 2.9.1
 296  */
 297 class wxFileTranslationsLoader : public wxTranslationsLoader
 298 {
 299 public:
 300     /**
 301         Add a prefix to the catalog lookup path: the message catalog files will
 302         be looked up under prefix/lang/LC_MESSAGES, prefix/lang and prefix
 303         (in this order).
 304
 305         This only applies to subsequent invocations of
 306         wxTranslations::AddCatalog().
 307     */
 308     static void AddCatalogLookupPathPrefix(const wxString& prefix);
 309 };
 310
 311 /**
 312     This loader makes it possible to load translations from Windows
 313     resources.
 314
 315     If you wish to store translation MO files in resources, you have to
 316     enable this loader before calling wxTranslations::AddCatalog() or
 317     wxLocale::AddCatalog():
 318
 319     @code
 320     wxTranslations::Get()->SetLoader(new wxResourceTranslationsLoader);
 321     @endcode
 322
 323     Translations are stored in resources as compiled MO files, with type
 324     set to "MOFILE" (unless you override GetResourceType()) and name
 325     consisting of the domain, followed by underscore, followed by language
 326     identification. For example, the relevant part of .rc file would look
 327     like this:
 328
 329     @code
 330     myapp_de     MOFILE   "catalogs/de/myapp.mo"
 331     myapp_fr     MOFILE   "catalogs/fr/myapp.mo"
 332     myapp_en_GB  MOFILE   "catalogs/en_GB/myapp.mo"
 333     @endcode
 334
 335     This class is only available on Windows.
 336
 337     @since 2.9.1
 338
 339  */
 340 class wxResourceTranslationsLoader : public wxTranslationsLoader
 341 {
 342 protected:
 343     /**
 344         Returns resource type to use for translations.
 345
 346         Default type is "MOFILE".
 347      */
 348     virtual wxString GetResourceType() const;
 349
 350     /**
 351         Returns handle of the module to load resources from.
 352
 353         By default, the main executable is used.
 354      */
 355     virtual WXHINSTANCE GetModule() const;
 356 };
 357
 358
 359
 360 // ============================================================================
 361 // Global functions/macros
 362 // ============================================================================
 363
 364 /** @addtogroup group_funcmacro_string */
 365 //@{
 366
 367 /**
 368     This macro is identical to _() but for the plural variant of
 369     wxGetTranslation().
 370
 371     @return A const wxString.
 372
 373     @header{wx/intl.h}
 374 */
 375 #define wxPLURAL(string, plural, n)
 376
 377 /**
 378     This macro doesn't do anything in the program code -- it simply expands to
 379     the value of its argument.
 380
 381     However it does have a purpose which is to mark the literal strings for the
 382     extraction into the message catalog created by @c xgettext program. Usually
 383     this is achieved using _() but that macro not only marks the string for
 384     extraction but also expands into a wxGetTranslation() call which means that
 385     it cannot be used in some situations, notably for static array
 386     initialization.
 387
 388     Here is an example which should make it more clear: suppose that you have a
 389     static array of strings containing the weekday names and which have to be
 390     translated (note that it is a bad example, really, as wxDateTime already
 391     can be used to get the localized week day names already). If you write:
 392
 393     @code
 394     static const char * const weekdays[] = { _("Mon"), ..., _("Sun") };
 395     ...
 396     // use weekdays[n] as usual
 397     @endcode
 398
 399     The code wouldn't compile because the function calls are forbidden in the
 400     array initializer. So instead you should do this:
 401
 402     @code
 403     static const char * const weekdays[] = { wxTRANSLATE("Mon"), ...,
 404     wxTRANSLATE("Sun") };
 405     ...
 406     // use wxGetTranslation(weekdays[n])
 407     @endcode
 408
 409     Note that although the code @b would compile if you simply omit
 410     wxTRANSLATE() in the above, it wouldn't work as expected because there
 411     would be no translations for the weekday names in the program message
 412     catalog and wxGetTranslation() wouldn't find them.
 413
 414     @return A const wxChar*.
 415
 416     @header{wx/intl.h}
 417 */
 418 #define wxTRANSLATE(string)
 419
 420 /**
 421     This function returns the translation of @a string in the current
 422     @c locale(). If the string is not found in any of the loaded message
 423     catalogs (see @ref overview_i18n), the original string is returned. In
 424     debug build, an error message is logged -- this should help to find the
 425     strings which were not yet translated.  If @a domain is specified then only
 426     that domain/catalog is searched for a matching string.  As this function is
 427     used very often, an alternative (and also common in Unix world) syntax is
 428     provided: the _() macro is defined to do the same thing as
 429     wxGetTranslation().
 430
 431     This function calls wxTranslations::GetString().
 432
 433     @note This function is not suitable for literal strings in Unicode builds
 434           since the literal strings must be enclosed into _T() or wxT() macro
 435           which makes them unrecognised by @c xgettext, and so they are not
 436           extracted to the message catalog. Instead, use the _() and wxPLURAL()
 437           macro for all literal strings.
 438
 439     @see wxGetTranslation(const wxString&, const wxString&, size_t, const wxString&)
 440
 441     @header{wx/intl.h}
 442 */
 443 const wxString& wxGetTranslation(const wxString& string,
 444                                  const wxString& domain = wxEmptyString);
 445
 446 /**
 447     This is an overloaded version of
 448     wxGetTranslation(const wxString&, const wxString&), please see its
 449     documentation for general information.
 450
 451     This version is used when retrieving translation of string that has
 452     different singular and plural forms in English or different plural forms in
 453     some other language. Like wxGetTranslation(const wxString&,const wxString&),
 454     the @a string parameter must contain the singular form of the string to be
 455     converted and is used as the key for the search in the catalog. The
 456     @a plural parameter is the plural form (in English). The parameter @a n is
 457     used to determine the plural form. If no message catalog is found,
 458     @a string is returned if "n == 1", otherwise @a plural is returned.
 459
 460     See GNU gettext Manual for additional information on plural forms handling:
 461     <http://www.gnu.org/software/gettext/manual/gettext.html#Plural-forms>
 462     For a shorter alternative see the wxPLURAL() macro.
 463
 464     This function calls wxLocale::GetString().
 465
 466     @header{wx/intl.h}
 467 */
 468 const wxString& wxGetTranslation(const wxString& string,
 469                                  const wxString& plural, size_t n,
 470                                  const wxString& domain = wxEmptyString);
 471
 472 /**
 473     This macro expands into a call to wxGetTranslation(), so it marks the
 474     message for the extraction by @c xgettext just as wxTRANSLATE() does, but
 475     also returns the translation of the string for the current locale during
 476     execution.
 477
 478     Don't confuse this with _T()!
 479
 480     @header{wx/intl.h}
 481 */
 482 const wxString& _(const wxString& string);
 483
 484 //@}
 485