]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/translation.h
Move code removing "-psn_xxx" command line arguments to common code.
[wxWidgets.git] / interface / wx / translation.h
CommitLineData
ea144923
VS
1/////////////////////////////////////////////////////////////////////////////
2// Name: translation.h
3// Purpose: wxTranslation class
4// Author: wxWidgets team
526954c5 5// Licence: wxWindows licence
ea144923
VS
6/////////////////////////////////////////////////////////////////////////////
7
8
9/**
10 This class allows to get translations for strings.
11
12 In wxWidgets this class manages message catalogs which contain the
13 translations of the strings used to the current language. Unlike wxLocale,
14 it isn't bound to locale. It can be used either independently of, or in
15 conjunction with wxLocale. In the latter case, you should initialize
16 wxLocale (which creates wxTranslations instance) first; in the former, you
17 need to create a wxTranslations object and Set() it manually.
18
19 Only one wxTranslations instance is active at a time; it is set with the
20 Set() method and obtained using Get().
21
22 Unlike wxLocale, wxTranslations' primary mean of identifying language
23 is by its "canonical name", i.e. ISO 639 code, possibly combined with
24 ISO 3166 country code and additional modifiers (examples include
25 "fr", "en_GB" or "ca@valencia"; see wxLocale::GetCanonicalName() for
26 more information). This allows apps using wxTranslations API to use even
27 languages not recognized by the operating system or not listed in
28 wxLanguage enum.
29
30 @since 2.9.1
31
01f953ef 32 @see wxLocale, wxTranslationsLoader, wxFileTranslationsLoader
ea144923
VS
33 */
34class wxTranslations
35{
36public:
37 /// Constructor
38 wxTranslations();
39
40 /**
41 Returns current translations object, may return NULL.
42
43 You must either call this early in app initialization code, or let
44 wxLocale do it for you.
45 */
46 static wxTranslations *Get();
47
48 /**
49 Sets current translations object.
50
51 Deletes previous translation object and takes ownership of @a t.
52 */
53 static void Set(wxTranslations *t);
54
55 /**
56 Changes loader use to read catalogs to a non-default one.
57
58 Deletes previous loader and takes ownership of @a loader.
59
bc71c3cd 60 @see wxTranslationsLoader, wxFileTranslationsLoader, wxResourceTranslationsLoader
ea144923
VS
61 */
62 void SetLoader(wxTranslationsLoader *loader);
63
64 /**
65 Sets translations language to use.
66
67 wxLANGUAGE_DEFAULT has special meaning: best suitable translation,
68 given user's preference and available translations, will be used.
69 */
70 void SetLanguage(wxLanguage lang);
71
72 /**
73 Sets translations language to use.
74
75 Empty @a lang string has the same meaning as wxLANGUAGE_DEFAULT in
76 SetLanguage(wxLanguage): best suitable translation, given user's
77 preference and available translations, will be used.
78 */
79 void SetLanguage(const wxString& lang);
80
5e306229
VS
81 /**
82 Returns list of all translations of @a domain that were found.
83
84 This method can be used e.g. to populate list of application's
85 translations offered to the user. To do this, pass the app's main
86 catalog as @a domain.
01f953ef
VS
87
88 @see GetBestTranslation()
5e306229
VS
89 */
90 wxArrayString GetAvailableTranslations(const wxString& domain) const;
91
01f953ef
VS
92 /**
93 Returns the best UI language for the @a domain.
94
95 The language is determined from the preferred UI language or languages
96 list the user configured in the OS. Notice that this may or may not
97 correspond to the default @em locale as obtained from
98 wxLocale::GetSystemLanguage(); modern operation systems (Windows
99 Vista+, OS X) have separate language and regional (= locale) settings.
100
101 @param domain
102 The catalog domain to look for.
103
104 @param msgIdLanguage
105 Specifies the language of "msgid" strings in source code
106 (i.e. arguments to GetString(), wxGetTranslation() and the _() macro).
107
108 @return Language code if a suitable match was found, empty string
109 otherwise.
110
111 @since 2.9.5
112 */
113 wxString GetBestTranslation(const wxString& domain, wxLanguage msgIdLanguage);
114
115 /**
116 Returns the best UI language for the @a domain.
117
118 The language is determined from the preferred UI language or languages
119 list the user configured in the OS. Notice that this may or may not
120 correspond to the default @em locale as obtained from
121 wxLocale::GetSystemLanguage(); modern operation systems (Windows
122 Vista+, OS X) have separate language and regional (= locale) settings.
123
124 @param domain
125 The catalog domain to look for.
126
127 @param msgIdLanguage
128 Specifies the language of "msgid" strings in source code
129 (i.e. arguments to GetString(), wxGetTranslation() and the _() macro).
130
131 @return Language code if a suitable match was found, empty string
132 otherwise.
133
134 @since 2.9.5
135 */
136 wxString GetBestTranslation(const wxString& domain,
137 const wxString& msgIdLanguage = "en");
138
ea144923
VS
139 /**
140 Add standard wxWidgets catalogs ("wxstd" and possible port-specific
141 catalogs).
142
143 @return @true if a suitable catalog was found, @false otherwise
144
145 @see AddCatalog()
146 */
147 bool AddStdCatalog();
148
149 /**
150 Add a catalog for use with the current locale.
151
152 By default, it is searched for in standard places (see
153 wxFileTranslationsLoader), but you may also prepend additional
154 directories to the search path with
155 wxFileTranslationsLoader::AddCatalogLookupPathPrefix().
156
157 All loaded catalogs will be used for message lookup by GetString() for
158 the current locale.
159
160 In this overload, @c msgid strings are assumed
161 to be in English and written only using 7-bit ASCII characters.
162 If you have to deal with non-English strings or 8-bit characters in the
163 source code, see the instructions in @ref overview_nonenglish.
164
165 @return
166 @true if catalog was successfully loaded, @false otherwise (which might
167 mean that the catalog is not found or that it isn't in the correct format).
168 */
169 bool AddCatalog(const wxString& domain);
170
171 /**
172 Same as AddCatalog(const wxString&), but takes an additional argument,
173 @a msgIdLanguage.
174
175 @param domain
176 The catalog domain to add.
177
178 @param msgIdLanguage
179 Specifies the language of "msgid" strings in source code
180 (i.e. arguments to GetString(), wxGetTranslation() and the _() macro).
181 It is used if AddCatalog() cannot find any catalog for current language:
182 if the language is same as source code language, then strings from source
183 code are used instead.
184
185 @return
186 @true if catalog was successfully loaded, @false otherwise (which might
187 mean that the catalog is not found or that it isn't in the correct format).
188 */
189 bool AddCatalog(const wxString& domain, wxLanguage msgIdLanguage);
190
191 /**
192 Same as AddCatalog(const wxString&, wxLanguage), but takes two
193 additional arguments, @a msgIdLanguage and @a msgIdCharset.
194
195 This overload is only available in non-Unicode build.
196
197 @param domain
198 The catalog domain to add.
199
200 @param msgIdLanguage
201 Specifies the language of "msgid" strings in source code
202 (i.e. arguments to GetString(), wxGetTranslation() and the _() macro).
203 It is used if AddCatalog() cannot find any catalog for current language:
204 if the language is same as source code language, then strings from source
205 code are used instead.
206
207 @param msgIdCharset
208 Lets you specify the charset used for msgids in sources
209 in case they use 8-bit characters (e.g. German or French strings).
210
211 @return
212 @true if catalog was successfully loaded, @false otherwise (which might
213 mean that the catalog is not found or that it isn't in the correct format).
214 */
215 bool AddCatalog(const wxString& domain,
216 wxLanguage msgIdLanguage,
217 const wxString& msgIdCharset);
218
219 /**
220 Check if the given catalog is loaded, and returns @true if it is.
221
222 According to GNU gettext tradition, each catalog normally corresponds to
223 'domain' which is more or less the application name.
224
225 @see AddCatalog()
226 */
227 bool IsLoaded(const wxString& domain) const;
228
ea144923
VS
229 /**
230 Retrieves the translation for a string in all loaded domains unless the @a domain
231 parameter is specified (and then only this catalog/domain is searched).
232
233 Returns original string if translation is not available (in this case an
234 error message is generated the first time a string is not found; use
235 wxLogNull to suppress it).
236
237 @remarks Domains are searched in the last to first order, i.e. catalogs
238 added later override those added before.
239 */
240 const wxString& GetString(const wxString& origString,
241 const wxString& domain = wxEmptyString) const;
242
243 /**
244 Retrieves the translation for a string in all loaded domains unless the @a domain
245 parameter is specified (and then only this catalog/domain is searched).
246
247 Returns original string if translation is not available (in this case an
248 error message is generated the first time a string is not found; use
249 wxLogNull to suppress it).
250
251 This form is used when retrieving translation of string that has different
252 singular and plural form in English or different plural forms in some
253 other language.
254 It takes two extra arguments: @a origString parameter must contain the
255 singular form of the string to be converted.
256
257 It is also used as the key for the search in the catalog.
258 The @a origString2 parameter is the plural form (in English).
259
260 The parameter @a n is used to determine the plural form.
261 If no message catalog is found @a origString is returned if 'n == 1',
262 otherwise @a origString2.
263
264 See GNU gettext manual for additional information on plural forms handling.
265 This method is called by the wxGetTranslation() function and _() macro.
266
267 @remarks Domains are searched in the last to first order, i.e. catalogs
268 added later override those added before.
269 */
270 const wxString& GetString(const wxString& origString,
271 const wxString& origString2,
dfbb5eff 272 unsigned n,
ea144923
VS
273 const wxString& domain = wxEmptyString) const;
274
275 /**
276 Returns the header value for header @a header.
277 The search for @a header is case sensitive. If an @a domain is passed,
278 this domain is searched. Else all domains will be searched until a
279 header has been found.
280
281 The return value is the value of the header if found. Else this will be empty.
282 */
283 wxString GetHeaderValue(const wxString& header,
284 const wxString& domain = wxEmptyString) const;
285};
286
287
288/**
289 Abstraction of translations discovery and loading.
290
291 This interface makes it possible to override wxWidgets' default catalogs
292 loading mechanism and load MO files from locations other than the
293 filesystem (e.g. embed them in executable).
294
295 Implementations must implement the LoadCatalog() method.
296
bc71c3cd 297 @see wxFileTranslationsLoader, wxResourceTranslationsLoader
7ed63042
VS
298
299 @since 2.9.1
ea144923
VS
300 */
301class wxTranslationsLoader
302{
303public:
29a3f654
VZ
304 /// Trivial default constructor.
305 wxTranslationsLoader();
ea144923
VS
306
307 /**
308 Called to load requested catalog.
309
611bed35
VS
310 If the catalog is found, LoadCatalog() should create wxMsgCatalog
311 instance with its data and return it. The caller will take ownership
312 of the catalog.
ea144923 313
ea144923
VS
314 @param domain Domain to load.
315 @param lang Language to look for. This is "canonical name"
316 (see wxLocale::GetCanonicalName()), i.e. ISO 639
317 code, possibly combined with country code or
318 additional modifiers (e.g. "fr", "en_GB" or
319 "ca@valencia").
320
611bed35 321 @return Loaded catalog or NULL on failure.
ea144923 322 */
611bed35
VS
323 virtual wxMsgCatalog *LoadCatalog(const wxString& domain,
324 const wxString& lang) = 0;
5e306229
VS
325
326 /**
327 Implements wxTranslations::GetAvailableTranslations().
328 */
329 virtual wxArrayString GetAvailableTranslations(const wxString& domain) const = 0;
ea144923
VS
330};
331
332/**
333 Standard wxTranslationsLoader implementation.
334
335 This finds catalogs in the filesystem, using the standard Unix layout.
336 This is the default unless you change the loader with
337 wxTranslations::SetLoader().
338
3f844591 339 Catalogs are searched for in standard places (system locales directory,
ea160f01
VS
340 `LC_PATH` on Unix systems, Resources subdirectory of the application bundle
341 on OS X, executable's directory on Windows), but you may also prepend
342 additional directories to the search path with
343 AddCatalogLookupPathPrefix().
7ed63042
VS
344
345 @since 2.9.1
ea144923
VS
346 */
347class wxFileTranslationsLoader : public wxTranslationsLoader
348{
349public:
350 /**
351 Add a prefix to the catalog lookup path: the message catalog files will
ea160f01 352 be looked up under prefix/lang/LC_MESSAGES and prefix/lang directories
ea144923
VS
353 (in this order).
354
355 This only applies to subsequent invocations of
356 wxTranslations::AddCatalog().
357 */
358 static void AddCatalogLookupPathPrefix(const wxString& prefix);
359};
360
bc71c3cd
VS
361/**
362 This loader makes it possible to load translations from Windows
363 resources.
364
365 If you wish to store translation MO files in resources, you have to
366 enable this loader before calling wxTranslations::AddCatalog() or
367 wxLocale::AddCatalog():
368
369 @code
370 wxTranslations::Get()->SetLoader(new wxResourceTranslationsLoader);
371 @endcode
372
373 Translations are stored in resources as compiled MO files, with type
374 set to "MOFILE" (unless you override GetResourceType()) and name
375 consisting of the domain, followed by underscore, followed by language
376 identification. For example, the relevant part of .rc file would look
377 like this:
378
379 @code
380 myapp_de MOFILE "catalogs/de/myapp.mo"
381 myapp_fr MOFILE "catalogs/fr/myapp.mo"
382 myapp_en_GB MOFILE "catalogs/en_GB/myapp.mo"
383 @endcode
384
385 This class is only available on Windows.
386
387 @since 2.9.1
bc71c3cd
VS
388 */
389class wxResourceTranslationsLoader : public wxTranslationsLoader
390{
391protected:
392 /**
393 Returns resource type to use for translations.
394
395 Default type is "MOFILE".
396 */
397 virtual wxString GetResourceType() const;
398
399 /**
400 Returns handle of the module to load resources from.
401
402 By default, the main executable is used.
403 */
404 virtual WXHINSTANCE GetModule() const;
405};
406
ea144923 407
611bed35
VS
408/**
409 Represents a loaded translations message catalog.
410
411 This class should only be used directly by wxTranslationsLoader
412 implementations.
413
414 @since 2.9.1
415 */
416class wxMsgCatalog
417{
418public:
419 /**
420 Creates catalog loaded from a MO file.
421
422 @param filename Path to the MO file to load.
423 @param domain Catalog's domain. This typically matches
424 the @a filename.
425
426 @return Successfully loaded catalog or NULL on failure.
427 */
428 static wxMsgCatalog *CreateFromFile(const wxString& filename,
429 const wxString& domain);
430
431 /**
432 Creates catalog from MO file data in memory buffer.
433
434 @param data Data in MO file format.
435 @param domain Catalog's domain. This typically matches
436 the @a filename.
437
438 @return Successfully loaded catalog or NULL on failure.
439 */
440 static wxMsgCatalog *CreateFromData(const wxScopedCharBuffer& data,
441 const wxString& domain);
442};
443
ea144923
VS
444
445// ============================================================================
446// Global functions/macros
447// ============================================================================
448
449/** @addtogroup group_funcmacro_string */
450//@{
451
452/**
453 This macro is identical to _() but for the plural variant of
454 wxGetTranslation().
455
456 @return A const wxString.
457
458 @header{wx/intl.h}
459*/
460#define wxPLURAL(string, plural, n)
461
462/**
463 This macro doesn't do anything in the program code -- it simply expands to
464 the value of its argument.
465
466 However it does have a purpose which is to mark the literal strings for the
467 extraction into the message catalog created by @c xgettext program. Usually
468 this is achieved using _() but that macro not only marks the string for
469 extraction but also expands into a wxGetTranslation() call which means that
470 it cannot be used in some situations, notably for static array
471 initialization.
472
473 Here is an example which should make it more clear: suppose that you have a
474 static array of strings containing the weekday names and which have to be
475 translated (note that it is a bad example, really, as wxDateTime already
476 can be used to get the localized week day names already). If you write:
477
478 @code
479 static const char * const weekdays[] = { _("Mon"), ..., _("Sun") };
480 ...
481 // use weekdays[n] as usual
482 @endcode
483
484 The code wouldn't compile because the function calls are forbidden in the
485 array initializer. So instead you should do this:
486
487 @code
488 static const char * const weekdays[] = { wxTRANSLATE("Mon"), ...,
489 wxTRANSLATE("Sun") };
490 ...
491 // use wxGetTranslation(weekdays[n])
492 @endcode
493
494 Note that although the code @b would compile if you simply omit
495 wxTRANSLATE() in the above, it wouldn't work as expected because there
496 would be no translations for the weekday names in the program message
497 catalog and wxGetTranslation() wouldn't find them.
498
499 @return A const wxChar*.
500
501 @header{wx/intl.h}
502*/
503#define wxTRANSLATE(string)
504
505/**
506 This function returns the translation of @a string in the current
507 @c locale(). If the string is not found in any of the loaded message
508 catalogs (see @ref overview_i18n), the original string is returned. In
509 debug build, an error message is logged -- this should help to find the
510 strings which were not yet translated. If @a domain is specified then only
511 that domain/catalog is searched for a matching string. As this function is
512 used very often, an alternative (and also common in Unix world) syntax is
513 provided: the _() macro is defined to do the same thing as
514 wxGetTranslation().
515
516 This function calls wxTranslations::GetString().
517
518 @note This function is not suitable for literal strings in Unicode builds
05fbf0e7
VZ
519 since the literal strings must be enclosed in wxT() macro which makes
520 them unrecognised by @c xgettext, and so they are not extracted to
521 the message catalog. Instead, use the _() and wxPLURAL() macro for
522 all literal strings.
ea144923 523
dfbb5eff 524 @see wxGetTranslation(const wxString&, const wxString&, unsigned, const wxString&)
ea144923
VS
525
526 @header{wx/intl.h}
527*/
528const wxString& wxGetTranslation(const wxString& string,
529 const wxString& domain = wxEmptyString);
530
531/**
532 This is an overloaded version of
533 wxGetTranslation(const wxString&, const wxString&), please see its
534 documentation for general information.
535
536 This version is used when retrieving translation of string that has
537 different singular and plural forms in English or different plural forms in
538 some other language. Like wxGetTranslation(const wxString&,const wxString&),
539 the @a string parameter must contain the singular form of the string to be
540 converted and is used as the key for the search in the catalog. The
541 @a plural parameter is the plural form (in English). The parameter @a n is
542 used to determine the plural form. If no message catalog is found,
543 @a string is returned if "n == 1", otherwise @a plural is returned.
544
545 See GNU gettext Manual for additional information on plural forms handling:
546 <http://www.gnu.org/software/gettext/manual/gettext.html#Plural-forms>
547 For a shorter alternative see the wxPLURAL() macro.
548
549 This function calls wxLocale::GetString().
550
551 @header{wx/intl.h}
552*/
553const wxString& wxGetTranslation(const wxString& string,
dfbb5eff 554 const wxString& plural, unsigned n,
ea144923
VS
555 const wxString& domain = wxEmptyString);
556
557/**
05fbf0e7
VZ
558 Macro to be used around all literal strings that should be translated.
559
ea144923
VS
560 This macro expands into a call to wxGetTranslation(), so it marks the
561 message for the extraction by @c xgettext just as wxTRANSLATE() does, but
562 also returns the translation of the string for the current locale during
563 execution.
564
ea144923
VS
565 @header{wx/intl.h}
566*/
567const wxString& _(const wxString& string);
568
569//@}
570