include/wx/translation.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/translation.h
   3 // Purpose:     Internationalization and localisation for wxWidgets
   4 // Author:      Vadim Zeitlin, Vaclav Slavik,
   5 //              Michael N. Filippov <michael@idisys.iae.nsk.su>
   6 // Created:     2010-04-23
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) 1998 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
   9 //              (c) 2010 Vaclav Slavik <vslavik@fastmail.fm>
  10 // Licence:     wxWindows licence
  11 /////////////////////////////////////////////////////////////////////////////
  12
  13 #ifndef _WX_TRANSLATION_H_
  14 #define _WX_TRANSLATION_H_
  15
  16 #include "wx/defs.h"
  17 #include "wx/string.h"
  18
  19 #if wxUSE_INTL
  20
  21 #include "wx/buffer.h"
  22 #include "wx/language.h"
  23 #include "wx/hashmap.h"
  24 #include "wx/strconv.h"
  25 #include "wx/scopedptr.h"
  26
  27 // ============================================================================
  28 // global decls
  29 // ============================================================================
  30
  31 // ----------------------------------------------------------------------------
  32 // macros
  33 // ----------------------------------------------------------------------------
  34
  35 // gettext() style macros (notice that xgettext should be invoked with
  36 // --keyword="_" --keyword="wxPLURAL:1,2" options
  37 // to extract the strings from the sources)
  38 #ifndef WXINTL_NO_GETTEXT_MACRO
  39     #define _(s)                     wxGetTranslation((s))
  40     #define wxPLURAL(sing, plur, n)  wxGetTranslation((sing), (plur), n)
  41 #endif
  42
  43 // another one which just marks the strings for extraction, but doesn't
  44 // perform the translation (use -kwxTRANSLATE with xgettext!)
  45 #define wxTRANSLATE(str) str
  46
  47 // ----------------------------------------------------------------------------
  48 // forward decls
  49 // ----------------------------------------------------------------------------
  50
  51 class WXDLLIMPEXP_FWD_BASE wxArrayString;
  52 class WXDLLIMPEXP_FWD_BASE wxTranslationsLoader;
  53 class WXDLLIMPEXP_FWD_BASE wxLocale;
  54
  55 class wxPluralFormsCalculator;
  56 wxDECLARE_SCOPED_PTR(wxPluralFormsCalculator, wxPluralFormsCalculatorPtr)
  57
  58 // ----------------------------------------------------------------------------
  59 // wxMsgCatalog corresponds to one loaded message catalog.
  60 // ----------------------------------------------------------------------------
  61
  62 class WXDLLIMPEXP_BASE wxMsgCatalog
  63 {
  64 public:
  65     // Ctor is protected, because CreateFromXXX functions must be used,
  66     // but destruction should be unrestricted
  67 #if !wxUSE_UNICODE
  68     ~wxMsgCatalog();
  69 #endif
  70
  71     // load the catalog from disk or from data; caller is responsible for
  72     // deleting them if not NULL
  73     static wxMsgCatalog *CreateFromFile(const wxString& filename,
  74                                         const wxString& domain);
  75
  76     static wxMsgCatalog *CreateFromData(const wxScopedCharBuffer& data,
  77                                         const wxString& domain);
  78
  79     // get name of the catalog
  80     wxString GetDomain() const { return m_domain; }
  81
  82     // get the translated string: returns NULL if not found
  83     const wxString *GetString(const wxString& sz, unsigned n = UINT_MAX) const;
  84
  85 protected:
  86     wxMsgCatalog(const wxString& domain)
  87         : m_pNext(NULL), m_domain(domain)
  88 #if !wxUSE_UNICODE
  89         , m_conv(NULL)
  90 #endif
  91     {}
  92
  93 private:
  94     // variable pointing to the next element in a linked list (or NULL)
  95     wxMsgCatalog *m_pNext;
  96     friend class wxTranslations;
  97
  98     wxStringToStringHashMap m_messages; // all messages in the catalog
  99     wxString                m_domain;   // name of the domain
 100
 101 #if !wxUSE_UNICODE
 102     // the conversion corresponding to this catalog charset if we installed it
 103     // as the global one
 104     wxCSConv *m_conv;
 105 #endif
 106
 107     wxPluralFormsCalculatorPtr m_pluralFormsCalculator;
 108 };
 109
 110 // ----------------------------------------------------------------------------
 111 // wxTranslations: message catalogs
 112 // ----------------------------------------------------------------------------
 113
 114 // this class allows to get translations for strings
 115 class WXDLLIMPEXP_BASE wxTranslations
 116 {
 117 public:
 118     wxTranslations();
 119     ~wxTranslations();
 120
 121     // returns current translations object, may return NULL
 122     static wxTranslations *Get();
 123     // sets current translations object (takes ownership; may be NULL)
 124     static void Set(wxTranslations *t);
 125
 126     // changes loader to non-default one; takes ownership of 'loader'
 127     void SetLoader(wxTranslationsLoader *loader);
 128
 129     void SetLanguage(wxLanguage lang);
 130     void SetLanguage(const wxString& lang);
 131
 132     // get languages available for this app
 133     wxArrayString GetAvailableTranslations(const wxString& domain) const;
 134
 135     // find best translation language for given domain
 136     wxString GetBestTranslation(const wxString& domain, wxLanguage msgIdLanguage);
 137     wxString GetBestTranslation(const wxString& domain,
 138                                 const wxString& msgIdLanguage = "en");
 139
 140     // add standard wxWidgets catalog ("wxstd")
 141     bool AddStdCatalog();
 142
 143     // add catalog with given domain name and language, looking it up via
 144     // wxTranslationsLoader
 145     bool AddCatalog(const wxString& domain);
 146     bool AddCatalog(const wxString& domain, wxLanguage msgIdLanguage);
 147 #if !wxUSE_UNICODE
 148     bool AddCatalog(const wxString& domain,
 149                     wxLanguage msgIdLanguage,
 150                     const wxString& msgIdCharset);
 151 #endif
 152
 153     // check if the given catalog is loaded
 154     bool IsLoaded(const wxString& domain) const;
 155
 156     // access to translations
 157     const wxString& GetString(const wxString& origString,
 158                               const wxString& domain = wxEmptyString) const;
 159     const wxString& GetString(const wxString& origString,
 160                               const wxString& origString2,
 161                               unsigned n,
 162                               const wxString& domain = wxEmptyString) const;
 163
 164     wxString GetHeaderValue(const wxString& header,
 165                             const wxString& domain = wxEmptyString) const;
 166
 167     // this is hack to work around a problem with wxGetTranslation() which
 168     // returns const wxString& and not wxString, so when it returns untranslated
 169     // string, it needs to have a copy of it somewhere
 170     static const wxString& GetUntranslatedString(const wxString& str);
 171
 172 private:
 173     // perform loading of the catalog via m_loader
 174     bool LoadCatalog(const wxString& domain, const wxString& lang);
 175
 176     // find catalog by name in a linked list, return NULL if !found
 177     wxMsgCatalog *FindCatalog(const wxString& domain) const;
 178
 179     // same as Set(), without taking ownership; only for wxLocale
 180     static void SetNonOwned(wxTranslations *t);
 181     friend class wxLocale;
 182
 183 private:
 184     wxString m_lang;
 185     wxTranslationsLoader *m_loader;
 186
 187     wxMsgCatalog *m_pMsgCat; // pointer to linked list of catalogs
 188 };
 189
 190
 191 // abstraction of translations discovery and loading
 192 class WXDLLIMPEXP_BASE wxTranslationsLoader
 193 {
 194 public:
 195     wxTranslationsLoader() {}
 196     virtual ~wxTranslationsLoader() {}
 197
 198     virtual wxMsgCatalog *LoadCatalog(const wxString& domain,
 199                                       const wxString& lang) = 0;
 200
 201     virtual wxArrayString GetAvailableTranslations(const wxString& domain) const = 0;
 202 };
 203
 204
 205 // standard wxTranslationsLoader implementation, using filesystem
 206 class WXDLLIMPEXP_BASE wxFileTranslationsLoader
 207     : public wxTranslationsLoader
 208 {
 209 public:
 210     static void AddCatalogLookupPathPrefix(const wxString& prefix);
 211
 212     virtual wxMsgCatalog *LoadCatalog(const wxString& domain,
 213                                       const wxString& lang);
 214
 215     virtual wxArrayString GetAvailableTranslations(const wxString& domain) const;
 216 };
 217
 218
 219 #ifdef __WINDOWS__
 220 // loads translations from win32 resources
 221 class WXDLLIMPEXP_BASE wxResourceTranslationsLoader
 222     : public wxTranslationsLoader
 223 {
 224 public:
 225     virtual wxMsgCatalog *LoadCatalog(const wxString& domain,
 226                                       const wxString& lang);
 227
 228     virtual wxArrayString GetAvailableTranslations(const wxString& domain) const;
 229
 230 protected:
 231     // returns resource type to use for translations
 232     virtual wxString GetResourceType() const { return "MOFILE"; }
 233
 234     // returns module to load resources from
 235     virtual WXHINSTANCE GetModule() const { return 0; }
 236 };
 237 #endif // __WINDOWS__
 238
 239
 240 // ----------------------------------------------------------------------------
 241 // global functions
 242 // ----------------------------------------------------------------------------
 243
 244 // get the translation of the string in the current locale
 245 inline const wxString& wxGetTranslation(const wxString& str,
 246                                         const wxString& domain = wxEmptyString)
 247 {
 248     wxTranslations *trans = wxTranslations::Get();
 249     if ( trans )
 250         return trans->GetString(str, domain);
 251     else
 252         // NB: this function returns reference to a string, so we have to keep
 253         //     a copy of it somewhere
 254         return wxTranslations::GetUntranslatedString(str);
 255 }
 256
 257 inline const wxString& wxGetTranslation(const wxString& str1,
 258                                         const wxString& str2,
 259                                         unsigned n,
 260                                         const wxString& domain = wxEmptyString)
 261 {
 262     wxTranslations *trans = wxTranslations::Get();
 263     if ( trans )
 264         return trans->GetString(str1, str2, n, domain);
 265     else
 266         // NB: this function returns reference to a string, so we have to keep
 267         //     a copy of it somewhere
 268         return n == 1
 269                ? wxTranslations::GetUntranslatedString(str1)
 270                : wxTranslations::GetUntranslatedString(str2);
 271 }
 272
 273 #else // !wxUSE_INTL
 274
 275 // the macros should still be defined - otherwise compilation would fail
 276
 277 #if !defined(WXINTL_NO_GETTEXT_MACRO)
 278     #if !defined(_)
 279         #define _(s)                 (s)
 280     #endif
 281     #define wxPLURAL(sing, plur, n)  ((n) == 1 ? (sing) : (plur))
 282 #endif
 283
 284 #define wxTRANSLATE(str) str
 285
 286 // NB: we use a template here in order to avoid using
 287 //     wxLocale::GetUntranslatedString() above, which would be required if
 288 //     we returned const wxString&; this way, the compiler should be able to
 289 //     optimize wxGetTranslation() away
 290
 291 template<typename TString>
 292 inline TString wxGetTranslation(TString str)
 293     { return str; }
 294
 295 template<typename TString, typename TDomain>
 296 inline TString wxGetTranslation(TString str, TDomain WXUNUSED(domain))
 297     { return str; }
 298
 299 template<typename TString, typename TDomain>
 300 inline TString wxGetTranslation(TString str1, TString str2, size_t n)
 301     { return n == 1 ? str1 : str2; }
 302
 303 template<typename TString, typename TDomain>
 304 inline TString wxGetTranslation(TString str1, TString str2, size_t n,
 305                                 TDomain WXUNUSED(domain))
 306     { return n == 1 ? str1 : str2; }
 307
 308 #endif // wxUSE_INTL/!wxUSE_INTL
 309
 310 // define this one just in case it occurs somewhere (instead of preferred
 311 // wxTRANSLATE) too
 312 #if !defined(WXINTL_NO_GETTEXT_MACRO)
 313     #if !defined(gettext_noop)
 314         #define gettext_noop(str) (str)
 315     #endif
 316     #if !defined(N_)
 317         #define N_(s)             (s)
 318     #endif
 319 #endif
 320
 321 #endif // _WX_TRANSLATION_H_