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     @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
 313 // ============================================================================
 314 // Global functions/macros
 315 // ============================================================================
 316
 317 /** @addtogroup group_funcmacro_string */
 318 //@{
 319
 320 /**
 321     This macro is identical to _() but for the plural variant of
 322     wxGetTranslation().
 323
 324     @return A const wxString.
 325
 326     @header{wx/intl.h}
 327 */
 328 #define wxPLURAL(string, plural, n)
 329
 330 /**
 331     This macro doesn't do anything in the program code -- it simply expands to
 332     the value of its argument.
 333
 334     However it does have a purpose which is to mark the literal strings for the
 335     extraction into the message catalog created by @c xgettext program. Usually
 336     this is achieved using _() but that macro not only marks the string for
 337     extraction but also expands into a wxGetTranslation() call which means that
 338     it cannot be used in some situations, notably for static array
 339     initialization.
 340
 341     Here is an example which should make it more clear: suppose that you have a
 342     static array of strings containing the weekday names and which have to be
 343     translated (note that it is a bad example, really, as wxDateTime already
 344     can be used to get the localized week day names already). If you write:
 345
 346     @code
 347     static const char * const weekdays[] = { _("Mon"), ..., _("Sun") };
 348     ...
 349     // use weekdays[n] as usual
 350     @endcode
 351
 352     The code wouldn't compile because the function calls are forbidden in the
 353     array initializer. So instead you should do this:
 354
 355     @code
 356     static const char * const weekdays[] = { wxTRANSLATE("Mon"), ...,
 357     wxTRANSLATE("Sun") };
 358     ...
 359     // use wxGetTranslation(weekdays[n])
 360     @endcode
 361
 362     Note that although the code @b would compile if you simply omit
 363     wxTRANSLATE() in the above, it wouldn't work as expected because there
 364     would be no translations for the weekday names in the program message
 365     catalog and wxGetTranslation() wouldn't find them.
 366
 367     @return A const wxChar*.
 368
 369     @header{wx/intl.h}
 370 */
 371 #define wxTRANSLATE(string)
 372
 373 /**
 374     This function returns the translation of @a string in the current
 375     @c locale(). If the string is not found in any of the loaded message
 376     catalogs (see @ref overview_i18n), the original string is returned. In
 377     debug build, an error message is logged -- this should help to find the
 378     strings which were not yet translated.  If @a domain is specified then only
 379     that domain/catalog is searched for a matching string.  As this function is
 380     used very often, an alternative (and also common in Unix world) syntax is
 381     provided: the _() macro is defined to do the same thing as
 382     wxGetTranslation().
 383
 384     This function calls wxTranslations::GetString().
 385
 386     @note This function is not suitable for literal strings in Unicode builds
 387           since the literal strings must be enclosed into _T() or wxT() macro
 388           which makes them unrecognised by @c xgettext, and so they are not
 389           extracted to the message catalog. Instead, use the _() and wxPLURAL()
 390           macro for all literal strings.
 391
 392     @see wxGetTranslation(const wxString&, const wxString&, size_t, const wxString&)
 393
 394     @header{wx/intl.h}
 395 */
 396 const wxString& wxGetTranslation(const wxString& string,
 397                                  const wxString& domain = wxEmptyString);
 398
 399 /**
 400     This is an overloaded version of
 401     wxGetTranslation(const wxString&, const wxString&), please see its
 402     documentation for general information.
 403
 404     This version is used when retrieving translation of string that has
 405     different singular and plural forms in English or different plural forms in
 406     some other language. Like wxGetTranslation(const wxString&,const wxString&),
 407     the @a string parameter must contain the singular form of the string to be
 408     converted and is used as the key for the search in the catalog. The
 409     @a plural parameter is the plural form (in English). The parameter @a n is
 410     used to determine the plural form. If no message catalog is found,
 411     @a string is returned if "n == 1", otherwise @a plural is returned.
 412
 413     See GNU gettext Manual for additional information on plural forms handling:
 414     <http://www.gnu.org/software/gettext/manual/gettext.html#Plural-forms>
 415     For a shorter alternative see the wxPLURAL() macro.
 416
 417     This function calls wxLocale::GetString().
 418
 419     @header{wx/intl.h}
 420 */
 421 const wxString& wxGetTranslation(const wxString& string,
 422                                  const wxString& plural, size_t n,
 423                                  const wxString& domain = wxEmptyString);
 424
 425 /**
 426     This macro expands into a call to wxGetTranslation(), so it marks the
 427     message for the extraction by @c xgettext just as wxTRANSLATE() does, but
 428     also returns the translation of the string for the current locale during
 429     execution.
 430
 431     Don't confuse this with _T()!
 432
 433     @header{wx/intl.h}
 434 */
 435 const wxString& _(const wxString& string);
 436
 437 //@}
 438