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
  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
 255  */
 256 class wxTranslationsLoader
 257 {
 258 public:
 259     /// Constructor
 260     wxTranslationsLoader() {}
 261
 262     /**
 263         Called to load requested catalog.
 264
 265         If the catalog is found, LoadCatalog() should call LoadCatalogFile()
 266         on @a translations to add the translation.
 267
 268         @param translations  wxTranslations requesting loading.
 269         @param domain        Domain to load.
 270         @param lang          Language to look for. This is "canonical name"
 271                              (see wxLocale::GetCanonicalName()), i.e. ISO 639
 272                              code, possibly combined with country code or
 273                              additional modifiers (e.g. "fr", "en_GB" or
 274                              "ca@valencia").
 275
 276         @return @true on successful load, @false otherwise
 277      */
 278     virtual bool LoadCatalog(wxTranslations *translations,
 279                              const wxString& domain, const wxString& lang) = 0;
 280 };
 281
 282 /**
 283     Standard wxTranslationsLoader implementation.
 284
 285     This finds catalogs in the filesystem, using the standard Unix layout.
 286     This is the default unless you change the loader with
 287     wxTranslations::SetLoader().
 288
 289     Catalogs are searched for in standard places (current directory first, then
 290     the system one), but you may also prepend additional directories to the
 291     search path with AddCatalogLookupPathPrefix().
 292  */
 293 class wxFileTranslationsLoader : public wxTranslationsLoader
 294 {
 295 public:
 296     /**
 297         Add a prefix to the catalog lookup path: the message catalog files will
 298         be looked up under prefix/lang/LC_MESSAGES, prefix/lang and prefix
 299         (in this order).
 300
 301         This only applies to subsequent invocations of
 302         wxTranslations::AddCatalog().
 303     */
 304     static void AddCatalogLookupPathPrefix(const wxString& prefix);
 305 };
 306
 307
 308
 309 // ============================================================================
 310 // Global functions/macros
 311 // ============================================================================
 312
 313 /** @addtogroup group_funcmacro_string */
 314 //@{
 315
 316 /**
 317     This macro is identical to _() but for the plural variant of
 318     wxGetTranslation().
 319
 320     @return A const wxString.
 321
 322     @header{wx/intl.h}
 323 */
 324 #define wxPLURAL(string, plural, n)
 325
 326 /**
 327     This macro doesn't do anything in the program code -- it simply expands to
 328     the value of its argument.
 329
 330     However it does have a purpose which is to mark the literal strings for the
 331     extraction into the message catalog created by @c xgettext program. Usually
 332     this is achieved using _() but that macro not only marks the string for
 333     extraction but also expands into a wxGetTranslation() call which means that
 334     it cannot be used in some situations, notably for static array
 335     initialization.
 336
 337     Here is an example which should make it more clear: suppose that you have a
 338     static array of strings containing the weekday names and which have to be
 339     translated (note that it is a bad example, really, as wxDateTime already
 340     can be used to get the localized week day names already). If you write:
 341
 342     @code
 343     static const char * const weekdays[] = { _("Mon"), ..., _("Sun") };
 344     ...
 345     // use weekdays[n] as usual
 346     @endcode
 347
 348     The code wouldn't compile because the function calls are forbidden in the
 349     array initializer. So instead you should do this:
 350
 351     @code
 352     static const char * const weekdays[] = { wxTRANSLATE("Mon"), ...,
 353     wxTRANSLATE("Sun") };
 354     ...
 355     // use wxGetTranslation(weekdays[n])
 356     @endcode
 357
 358     Note that although the code @b would compile if you simply omit
 359     wxTRANSLATE() in the above, it wouldn't work as expected because there
 360     would be no translations for the weekday names in the program message
 361     catalog and wxGetTranslation() wouldn't find them.
 362
 363     @return A const wxChar*.
 364
 365     @header{wx/intl.h}
 366 */
 367 #define wxTRANSLATE(string)
 368
 369 /**
 370     This function returns the translation of @a string in the current
 371     @c locale(). If the string is not found in any of the loaded message
 372     catalogs (see @ref overview_i18n), the original string is returned. In
 373     debug build, an error message is logged -- this should help to find the
 374     strings which were not yet translated.  If @a domain is specified then only
 375     that domain/catalog is searched for a matching string.  As this function is
 376     used very often, an alternative (and also common in Unix world) syntax is
 377     provided: the _() macro is defined to do the same thing as
 378     wxGetTranslation().
 379
 380     This function calls wxTranslations::GetString().
 381
 382     @note This function is not suitable for literal strings in Unicode builds
 383           since the literal strings must be enclosed into _T() or wxT() macro
 384           which makes them unrecognised by @c xgettext, and so they are not
 385           extracted to the message catalog. Instead, use the _() and wxPLURAL()
 386           macro for all literal strings.
 387
 388     @see wxGetTranslation(const wxString&, const wxString&, size_t, const wxString&)
 389
 390     @header{wx/intl.h}
 391 */
 392 const wxString& wxGetTranslation(const wxString& string,
 393                                  const wxString& domain = wxEmptyString);
 394
 395 /**
 396     This is an overloaded version of
 397     wxGetTranslation(const wxString&, const wxString&), please see its
 398     documentation for general information.
 399
 400     This version is used when retrieving translation of string that has
 401     different singular and plural forms in English or different plural forms in
 402     some other language. Like wxGetTranslation(const wxString&,const wxString&),
 403     the @a string parameter must contain the singular form of the string to be
 404     converted and is used as the key for the search in the catalog. The
 405     @a plural parameter is the plural form (in English). The parameter @a n is
 406     used to determine the plural form. If no message catalog is found,
 407     @a string is returned if "n == 1", otherwise @a plural is returned.
 408
 409     See GNU gettext Manual for additional information on plural forms handling:
 410     <http://www.gnu.org/software/gettext/manual/gettext.html#Plural-forms>
 411     For a shorter alternative see the wxPLURAL() macro.
 412
 413     This function calls wxLocale::GetString().
 414
 415     @header{wx/intl.h}
 416 */
 417 const wxString& wxGetTranslation(const wxString& string,
 418                                  const wxString& plural, size_t n,
 419                                  const wxString& domain = wxEmptyString);
 420
 421 /**
 422     This macro expands into a call to wxGetTranslation(), so it marks the
 423     message for the extraction by @c xgettext just as wxTRANSLATE() does, but
 424     also returns the translation of the string for the current locale during
 425     execution.
 426
 427     Don't confuse this with _T()!
 428
 429     @header{wx/intl.h}
 430 */
 431 const wxString& _(const wxString& string);
 432
 433 //@}
 434