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/language.h"
  22
  23 #if !wxUSE_UNICODE
  24     #include "wx/hashmap.h"
  25 #endif
  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 wxTranslationsLoader;
  52 class WXDLLIMPEXP_FWD_BASE wxLocale;
  53 class wxMsgCatalog;
  54
  55 // ----------------------------------------------------------------------------
  56 // wxTranslations: message catalogs
  57 // ----------------------------------------------------------------------------
  58
  59 // this class allows to get translations for strings
  60 class WXDLLIMPEXP_BASE wxTranslations
  61 {
  62 public:
  63     wxTranslations();
  64     ~wxTranslations();
  65
  66     // returns current translations object, may return NULL
  67     static wxTranslations *Get();
  68     // sets current translations object (takes ownership; may be NULL)
  69     static void Set(wxTranslations *t);
  70
  71     // changes loader to non-default one; takes ownership of 'loader'
  72     void SetLoader(wxTranslationsLoader *loader);
  73
  74     void SetLanguage(wxLanguage lang);
  75     void SetLanguage(const wxString& lang);
  76
  77     // add standard wxWidgets catalog ("wxstd")
  78     bool AddStdCatalog();
  79
  80     // add catalog with given domain name and language, looking it up via
  81     // wxTranslationsLoader
  82     bool AddCatalog(const wxString& domain);
  83     bool AddCatalog(const wxString& domain, wxLanguage msgIdLanguage);
  84 #if !wxUSE_UNICODE
  85     bool AddCatalog(const wxString& domain,
  86                     wxLanguage msgIdLanguage,
  87                     const wxString& msgIdCharset);
  88 #endif
  89
  90     // check if the given catalog is loaded
  91     bool IsLoaded(const wxString& domain) const;
  92
  93     // load catalog data directly from file
  94     bool LoadCatalogFile(const wxString& filename,
  95                          const wxString& domain = wxEmptyString);
  96
  97     // access to translations
  98     const wxString& GetString(const wxString& origString,
  99                               const wxString& domain = wxEmptyString) const;
 100     const wxString& GetString(const wxString& origString,
 101                               const wxString& origString2,
 102                               size_t n,
 103                               const wxString& domain = wxEmptyString) const;
 104
 105     wxString GetHeaderValue(const wxString& header,
 106                             const wxString& domain = wxEmptyString) const;
 107
 108     // this is hack to work around a problem with wxGetTranslation() which
 109     // returns const wxString& and not wxString, so when it returns untranslated
 110     // string, it needs to have a copy of it somewhere
 111     static const wxString& GetUntranslatedString(const wxString& str);
 112
 113 private:
 114     // perform loading of the catalog via m_loader
 115     bool LoadCatalog(const wxString& domain, const wxString& lang);
 116
 117     // find best translation for given domain
 118     wxString ChooseLanguageForDomain(const wxString& domain,
 119                                      const wxString& msgIdLang);
 120
 121     // find catalog by name in a linked list, return NULL if !found
 122     wxMsgCatalog *FindCatalog(const wxString& domain) const;
 123
 124     // same as Set(), without taking ownership; only for wxLocale
 125     static void SetNonOwned(wxTranslations *t);
 126     friend class wxLocale;
 127
 128 private:
 129     wxString m_lang;
 130     wxTranslationsLoader *m_loader;
 131
 132     wxMsgCatalog *m_pMsgCat; // pointer to linked list of catalogs
 133
 134 #if !wxUSE_UNICODE
 135     wxStringToStringHashMap m_msgIdCharset;
 136 #endif
 137 };
 138
 139
 140 // abstraction of translations discovery and loading
 141 class WXDLLIMPEXP_BASE wxTranslationsLoader
 142 {
 143 public:
 144     wxTranslationsLoader() {}
 145     virtual ~wxTranslationsLoader() {}
 146
 147     virtual bool LoadCatalog(wxTranslations *translations,
 148                              const wxString& domain, const wxString& lang) = 0;
 149 };
 150
 151 // standard wxTranslationsLoader implementation, using filesystem
 152 class WXDLLIMPEXP_BASE wxFileTranslationsLoader
 153     : public wxTranslationsLoader
 154 {
 155 public:
 156     static void AddCatalogLookupPathPrefix(const wxString& prefix);
 157
 158     virtual bool LoadCatalog(wxTranslations *translations,
 159                              const wxString& domain, const wxString& lang);
 160 };
 161
 162
 163 // ----------------------------------------------------------------------------
 164 // global functions
 165 // ----------------------------------------------------------------------------
 166
 167 // get the translation of the string in the current locale
 168 inline const wxString& wxGetTranslation(const wxString& str,
 169                                         const wxString& domain = wxEmptyString)
 170 {
 171     wxTranslations *trans = wxTranslations::Get();
 172     if ( trans )
 173         return trans->GetString(str, domain);
 174     else
 175         // NB: this function returns reference to a string, so we have to keep
 176         //     a copy of it somewhere
 177         return wxTranslations::GetUntranslatedString(str);
 178 }
 179
 180 inline const wxString& wxGetTranslation(const wxString& str1,
 181                                         const wxString& str2,
 182                                         size_t n,
 183                                         const wxString& domain = wxEmptyString)
 184 {
 185     wxTranslations *trans = wxTranslations::Get();
 186     if ( trans )
 187         return trans->GetString(str1, str2, n, domain);
 188     else
 189         // NB: this function returns reference to a string, so we have to keep
 190         //     a copy of it somewhere
 191         return n == 1
 192                ? wxTranslations::GetUntranslatedString(str1)
 193                : wxTranslations::GetUntranslatedString(str2);
 194 }
 195
 196 #else // !wxUSE_INTL
 197
 198 // the macros should still be defined - otherwise compilation would fail
 199
 200 #if !defined(WXINTL_NO_GETTEXT_MACRO)
 201     #if !defined(_)
 202         #define _(s)                 (s)
 203     #endif
 204     #define wxPLURAL(sing, plur, n)  ((n) == 1 ? (sing) : (plur))
 205 #endif
 206
 207 #define wxTRANSLATE(str) str
 208
 209 // NB: we use a template here in order to avoid using
 210 //     wxLocale::GetUntranslatedString() above, which would be required if
 211 //     we returned const wxString&; this way, the compiler should be able to
 212 //     optimize wxGetTranslation() away
 213
 214 template<typename TString>
 215 inline TString wxGetTranslation(TString str)
 216     { return str; }
 217
 218 template<typename TString, typename TDomain>
 219 inline TString wxGetTranslation(TString str, TDomain WXUNUSED(domain))
 220     { return str; }
 221
 222 template<typename TString, typename TDomain>
 223 inline TString wxGetTranslation(TString str1, TString str2, size_t n)
 224     { return n == 1 ? str1 : str2; }
 225
 226 template<typename TString, typename TDomain>
 227 inline TString wxGetTranslation(TString str1, TString str2, size_t n,
 228                                 TDomain WXUNUSED(domain))
 229     { return n == 1 ? str1 : str2; }
 230
 231 #endif // wxUSE_INTL/!wxUSE_INTL
 232
 233 // define this one just in case it occurs somewhere (instead of preferred
 234 // wxTRANSLATE) too
 235 #if !defined(WXINTL_NO_GETTEXT_MACRO)
 236     #if !defined(gettext_noop)
 237         #define gettext_noop(str) (str)
 238     #endif
 239     #if !defined(N_)
 240         #define N_(s)             (s)
 241     #endif
 242 #endif
 243
 244 #endif // _WX_TRANSLATION_H_