git.saurik.com Git - wxWidgets.git/blob - 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

9 // Licence: wxWindows licence

10 /////////////////////////////////////////////////////////////////////////////

12 #ifndef _WX_TRANSLATION_H_

13 #define _WX_TRANSLATION_H_

15 #include "wx/defs.h"

16 #include "wx/string.h"

18 #if wxUSE_INTL

20 #include "wx/buffer.h"

21 #include "wx/language.h"

22 #include "wx/hashmap.h"

23 #include "wx/strconv.h"

24 #include "wx/scopedptr.h"

26 // ============================================================================

27 // global decls

28 // ============================================================================

30 // ----------------------------------------------------------------------------

31 // macros

32 // ----------------------------------------------------------------------------

34 // gettext() style macros (notice that xgettext should be invoked with

35 // --keyword="_" --keyword="wxPLURAL:1,2" options

36 // to extract the strings from the sources)

37 #ifndef WXINTL_NO_GETTEXT_MACRO

38 #define _(s) wxGetTranslation((s))

39 #define wxPLURAL(sing, plur, n) wxGetTranslation((sing), (plur), n)

40 #endif

42 // another one which just marks the strings for extraction, but doesn't

43 // perform the translation (use -kwxTRANSLATE with xgettext!)

44 #define wxTRANSLATE(str) str

46 // ----------------------------------------------------------------------------

47 // forward decls

48 // ----------------------------------------------------------------------------

50 class WXDLLIMPEXP_FWD_BASE wxArrayString;

51 class WXDLLIMPEXP_FWD_BASE wxTranslationsLoader;

52 class WXDLLIMPEXP_FWD_BASE wxLocale;

54 class wxPluralFormsCalculator;

55 wxDECLARE_SCOPED_PTR(wxPluralFormsCalculator, wxPluralFormsCalculatorPtr)

57 // ----------------------------------------------------------------------------

58 // wxMsgCatalog corresponds to one loaded message catalog.

59 // ----------------------------------------------------------------------------

61 class WXDLLIMPEXP_BASE wxMsgCatalog

62 {

63 public:

64 // Ctor is protected, because CreateFromXXX functions must be used,

65 // but destruction should be unrestricted

66 #if !wxUSE_UNICODE

67 ~wxMsgCatalog();

68 #endif

70 // load the catalog from disk or from data; caller is responsible for

71 // deleting them if not NULL

     static wxMsgCatalog *CreateFromFile(const wxString& filename,

73 const wxString& domain);

     static wxMsgCatalog *CreateFromData(const wxScopedCharBuffer& data,

76 const wxString& domain);

78 // get name of the catalog

     wxString GetDomain() const { return m_domain; }

81 // get the translated string: returns NULL if not found

     const wxString *GetString(const wxString& sz, unsigned n = UINT_MAX) const;

84 protected:

     wxMsgCatalog(const wxString& domain)

         : m_pNext(NULL), m_domain(domain)

87 #if !wxUSE_UNICODE

88 , m_conv(NULL)

89 #endif

90 {}

92 private:

93 // variable pointing to the next element in a linked list (or NULL)

94 wxMsgCatalog *m_pNext;

95 friend class wxTranslations;

97 wxStringToStringHashMap m_messages; // all messages in the catalog

98 wxString m_domain; // name of the domain

100 #if !wxUSE_UNICODE

101 // the conversion corresponding to this catalog charset if we installed it

102 // as the global one

103 wxCSConv *m_conv;

104 #endif

105

106 wxPluralFormsCalculatorPtr m_pluralFormsCalculator;

107 };

108

109 // ----------------------------------------------------------------------------

110 // wxTranslations: message catalogs

111 // ----------------------------------------------------------------------------

112

113 // this class allows to get translations for strings

114 class WXDLLIMPEXP_BASE wxTranslations

115 {

116 public:

117 wxTranslations();

118 ~wxTranslations();

119

120 // returns current translations object, may return NULL

121 static wxTranslations *Get();

122 // sets current translations object (takes ownership; may be NULL)

     static void Set(wxTranslations *t);

124

125 // changes loader to non-default one; takes ownership of 'loader'

     void SetLoader(wxTranslationsLoader *loader);

127

128 void SetLanguage(wxLanguage lang);

     void SetLanguage(const wxString& lang);

130

131 // get languages available for this app

     wxArrayString GetAvailableTranslations(const wxString& domain) const;

133

134 // find best translation language for given domain

     wxString GetBestTranslation(const wxString& domain, wxLanguage msgIdLanguage);

     wxString GetBestTranslation(const wxString& domain,

                                 const wxString& msgIdLanguage = "en");

138

139 // add standard wxWidgets catalog ("wxstd")

140 bool AddStdCatalog();

141

142 // add catalog with given domain name and language, looking it up via

143 // wxTranslationsLoader

     bool AddCatalog(const wxString& domain);

     bool AddCatalog(const wxString& domain, wxLanguage msgIdLanguage);

146 #if !wxUSE_UNICODE

     bool AddCatalog(const wxString& domain,

148 wxLanguage msgIdLanguage,

149 const wxString& msgIdCharset);

150 #endif

151

152 // check if the given catalog is loaded

     bool IsLoaded(const wxString& domain) const;

154

155 // access to translations

     const wxString *GetTranslatedString(const wxString& origString,

                                         const wxString& domain = wxEmptyString) const;

     const wxString *GetTranslatedString(const wxString& origString,

159 unsigned n,

                                         const wxString& domain = wxEmptyString) const;

161

     wxString GetHeaderValue(const wxString& header,

                             const wxString& domain = wxEmptyString) const;

164

165 // this is hack to work around a problem with wxGetTranslation() which

166 // returns const wxString& and not wxString, so when it returns untranslated

167 // string, it needs to have a copy of it somewhere

     static const wxString& GetUntranslatedString(const wxString& str);

169

170 private:

171 // perform loading of the catalog via m_loader

     bool LoadCatalog(const wxString& domain, const wxString& lang, const wxString& msgIdLang);

173

174 // find catalog by name in a linked list, return NULL if !found

     wxMsgCatalog *FindCatalog(const wxString& domain) const;

176

177 // same as Set(), without taking ownership; only for wxLocale

     static void SetNonOwned(wxTranslations *t);

179 friend class wxLocale;

180

181 private:

182 wxString m_lang;

183 wxTranslationsLoader *m_loader;

184

185 wxMsgCatalog *m_pMsgCat; // pointer to linked list of catalogs

186 };

187

188

189 // abstraction of translations discovery and loading

190 class WXDLLIMPEXP_BASE wxTranslationsLoader

191 {

192 public:

193 wxTranslationsLoader() {}

194 virtual ~wxTranslationsLoader() {}

195

     virtual wxMsgCatalog *LoadCatalog(const wxString& domain,

                                       const wxString& lang) = 0;

198

     virtual wxArrayString GetAvailableTranslations(const wxString& domain) const = 0;

200 };

201

202

203 // standard wxTranslationsLoader implementation, using filesystem

204 class WXDLLIMPEXP_BASE wxFileTranslationsLoader

205 : public wxTranslationsLoader

206 {

207 public:

     static void AddCatalogLookupPathPrefix(const wxString& prefix);

209

     virtual wxMsgCatalog *LoadCatalog(const wxString& domain,

211 const wxString& lang);

212

     virtual wxArrayString GetAvailableTranslations(const wxString& domain) const;

214 };

215

216

217 #ifdef __WINDOWS__

218 // loads translations from win32 resources

219 class WXDLLIMPEXP_BASE wxResourceTranslationsLoader

220 : public wxTranslationsLoader

221 {

222 public:

     virtual wxMsgCatalog *LoadCatalog(const wxString& domain,

224 const wxString& lang);

225

     virtual wxArrayString GetAvailableTranslations(const wxString& domain) const;

227

228 protected:

229 // returns resource type to use for translations

     virtual wxString GetResourceType() const { return "MOFILE"; }

231

232 // returns module to load resources from

     virtual WXHINSTANCE GetModule() const { return 0; }

234 };

235 #endif // __WINDOWS__

236

237

238 // ----------------------------------------------------------------------------

239 // global functions

240 // ----------------------------------------------------------------------------

241

242 // get the translation of the string in the current locale

 inline const wxString& wxGetTranslation(const wxString& str,

                                         const wxString& domain = wxString())

245 {

     wxTranslations *trans = wxTranslations::Get();

     const wxString *transStr = trans ? trans->GetTranslatedString(str, domain)

248 : NULL;

249 if ( transStr )

250 return *transStr;

251 else

252 // NB: this function returns reference to a string, so we have to keep

253 // a copy of it somewhere

         return wxTranslations::GetUntranslatedString(str);

255 }

256

 inline const wxString& wxGetTranslation(const wxString& str1,

258 const wxString& str2,

259 unsigned n,

                                         const wxString& domain = wxString())

261 {

     wxTranslations *trans = wxTranslations::Get();

     const wxString *transStr = trans ? trans->GetTranslatedString(str1, n, domain)

264 : NULL;

265 if ( transStr )

266 return *transStr;

267 else

268 // NB: this function returns reference to a string, so we have to keep

269 // a copy of it somewhere

270 return n == 1

                ? wxTranslations::GetUntranslatedString(str1)

                : wxTranslations::GetUntranslatedString(str2);

273 }

274

275 #else // !wxUSE_INTL

276

277 // the macros should still be defined - otherwise compilation would fail

278

279 #if !defined(WXINTL_NO_GETTEXT_MACRO)

280 #if !defined(_)

281 #define _(s) (s)

282 #endif

283 #define wxPLURAL(sing, plur, n) ((n) == 1 ? (sing) : (plur))

284 #endif

285

286 #define wxTRANSLATE(str) str

287

288 // NB: we use a template here in order to avoid using

289 // wxLocale::GetUntranslatedString() above, which would be required if

290 // we returned const wxString&; this way, the compiler should be able to

291 // optimize wxGetTranslation() away

292

293 template<typename TString>

294 inline TString wxGetTranslation(TString str)

295 { return str; }

296

297 template<typename TString, typename TDomain>

 inline TString wxGetTranslation(TString str, TDomain WXUNUSED(domain))

299 { return str; }

300

301 template<typename TString, typename TDomain>

 inline TString wxGetTranslation(TString str1, TString str2, size_t n)

     { return n == 1 ? str1 : str2; }

304

305 template<typename TString, typename TDomain>

 inline TString wxGetTranslation(TString str1, TString str2, size_t n,

307 TDomain WXUNUSED(domain))

     { return n == 1 ? str1 : str2; }

309

310 #endif // wxUSE_INTL/!wxUSE_INTL

311

312 // define this one just in case it occurs somewhere (instead of preferred

313 // wxTRANSLATE) too

314 #if !defined(WXINTL_NO_GETTEXT_MACRO)

315 #if !defined(gettext_noop)

316 #define gettext_noop(str) (str)

317 #endif

318 #if !defined(N_)

319 #define N_(s) (s)

320 #endif

321 #endif

322

323 #endif // _WX_TRANSLATION_H_