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