--- /dev/null
+/////////////////////////////////////////////////////////////////////////////
+// Name: translation.h
+// Purpose: wxTranslation class
+// Author: wxWidgets team
+// RCS-ID: $Id$
+// Licence: wxWindows license
+/////////////////////////////////////////////////////////////////////////////
+
+
+/**
+ This class allows to get translations for strings.
+
+ In wxWidgets this class manages message catalogs which contain the
+ translations of the strings used to the current language. Unlike wxLocale,
+ it isn't bound to locale. It can be used either independently of, or in
+ conjunction with wxLocale. In the latter case, you should initialize
+ wxLocale (which creates wxTranslations instance) first; in the former, you
+ need to create a wxTranslations object and Set() it manually.
+
+ Only one wxTranslations instance is active at a time; it is set with the
+ Set() method and obtained using Get().
+
+ Unlike wxLocale, wxTranslations' primary mean of identifying language
+ is by its "canonical name", i.e. ISO 639 code, possibly combined with
+ ISO 3166 country code and additional modifiers (examples include
+ "fr", "en_GB" or "ca@valencia"; see wxLocale::GetCanonicalName() for
+ more information). This allows apps using wxTranslations API to use even
+ languages not recognized by the operating system or not listed in
+ wxLanguage enum.
+
+ @since 2.9.1
+
+ @see wxLocale
+ */
+class wxTranslations
+{
+public:
+ /// Constructor
+ wxTranslations();
+
+ /**
+ Returns current translations object, may return NULL.
+
+ You must either call this early in app initialization code, or let
+ wxLocale do it for you.
+ */
+ static wxTranslations *Get();
+
+ /**
+ Sets current translations object.
+
+ Deletes previous translation object and takes ownership of @a t.
+ */
+ static void Set(wxTranslations *t);
+
+ /**
+ Changes loader use to read catalogs to a non-default one.
+
+ Deletes previous loader and takes ownership of @a loader.
+
+ @see wxTranslationsLoader, wxFileTranslationsLoader
+ */
+ void SetLoader(wxTranslationsLoader *loader);
+
+ /**
+ Sets translations language to use.
+
+ wxLANGUAGE_DEFAULT has special meaning: best suitable translation,
+ given user's preference and available translations, will be used.
+ */
+ void SetLanguage(wxLanguage lang);
+
+ /**
+ Sets translations language to use.
+
+ Empty @a lang string has the same meaning as wxLANGUAGE_DEFAULT in
+ SetLanguage(wxLanguage): best suitable translation, given user's
+ preference and available translations, will be used.
+ */
+ void SetLanguage(const wxString& lang);
+
+ /**
+ Add standard wxWidgets catalogs ("wxstd" and possible port-specific
+ catalogs).
+
+ @return @true if a suitable catalog was found, @false otherwise
+
+ @see AddCatalog()
+ */
+ bool AddStdCatalog();
+
+ /**
+ Add a catalog for use with the current locale.
+
+ By default, it is searched for in standard places (see
+ wxFileTranslationsLoader), but you may also prepend additional
+ directories to the search path with
+ wxFileTranslationsLoader::AddCatalogLookupPathPrefix().
+
+ All loaded catalogs will be used for message lookup by GetString() for
+ the current locale.
+
+ In this overload, @c msgid strings are assumed
+ to be in English and written only using 7-bit ASCII characters.
+ If you have to deal with non-English strings or 8-bit characters in the
+ source code, see the instructions in @ref overview_nonenglish.
+
+ @return
+ @true if catalog was successfully loaded, @false otherwise (which might
+ mean that the catalog is not found or that it isn't in the correct format).
+ */
+ bool AddCatalog(const wxString& domain);
+
+ /**
+ Same as AddCatalog(const wxString&), but takes an additional argument,
+ @a msgIdLanguage.
+
+ @param domain
+ The catalog domain to add.
+
+ @param msgIdLanguage
+ Specifies the language of "msgid" strings in source code
+ (i.e. arguments to GetString(), wxGetTranslation() and the _() macro).
+ It is used if AddCatalog() cannot find any catalog for current language:
+ if the language is same as source code language, then strings from source
+ code are used instead.
+
+ @return
+ @true if catalog was successfully loaded, @false otherwise (which might
+ mean that the catalog is not found or that it isn't in the correct format).
+ */
+ bool AddCatalog(const wxString& domain, wxLanguage msgIdLanguage);
+
+ /**
+ Same as AddCatalog(const wxString&, wxLanguage), but takes two
+ additional arguments, @a msgIdLanguage and @a msgIdCharset.
+
+ This overload is only available in non-Unicode build.
+
+ @param domain
+ The catalog domain to add.
+
+ @param msgIdLanguage
+ Specifies the language of "msgid" strings in source code
+ (i.e. arguments to GetString(), wxGetTranslation() and the _() macro).
+ It is used if AddCatalog() cannot find any catalog for current language:
+ if the language is same as source code language, then strings from source
+ code are used instead.
+
+ @param msgIdCharset
+ Lets you specify the charset used for msgids in sources
+ in case they use 8-bit characters (e.g. German or French strings).
+
+ @return
+ @true if catalog was successfully loaded, @false otherwise (which might
+ mean that the catalog is not found or that it isn't in the correct format).
+ */
+ bool AddCatalog(const wxString& domain,
+ wxLanguage msgIdLanguage,
+ const wxString& msgIdCharset);
+
+ /**
+ Check if the given catalog is loaded, and returns @true if it is.
+
+ According to GNU gettext tradition, each catalog normally corresponds to
+ 'domain' which is more or less the application name.
+
+ @see AddCatalog()
+ */
+ bool IsLoaded(const wxString& domain) const;
+
+ /**
+ Directly loads catalog from a file.
+
+ It is caller's responsibility to ensure that the catalog contains
+ correct language. This function is primarily intended for
+ wxTranslationsLoader implementations.
+
+ @param filename Name of the MO file to load.
+ @param domain Domain to load the translations into (typically
+ matches file's basename).
+ */
+ bool LoadCatalogFile(const wxString& filename,
+ const wxString& domain = wxEmptyString);
+
+ /**
+ Retrieves the translation for a string in all loaded domains unless the @a domain
+ parameter is specified (and then only this catalog/domain is searched).
+
+ Returns original string if translation is not available (in this case an
+ error message is generated the first time a string is not found; use
+ wxLogNull to suppress it).
+
+ @remarks Domains are searched in the last to first order, i.e. catalogs
+ added later override those added before.
+ */
+ const wxString& GetString(const wxString& origString,
+ const wxString& domain = wxEmptyString) const;
+
+ /**
+ Retrieves the translation for a string in all loaded domains unless the @a domain
+ parameter is specified (and then only this catalog/domain is searched).
+
+ Returns original string if translation is not available (in this case an
+ error message is generated the first time a string is not found; use
+ wxLogNull to suppress it).
+
+ This form is used when retrieving translation of string that has different
+ singular and plural form in English or different plural forms in some
+ other language.
+ It takes two extra arguments: @a origString parameter must contain the
+ singular form of the string to be converted.
+
+ It is also used as the key for the search in the catalog.
+ The @a origString2 parameter is the plural form (in English).
+
+ The parameter @a n is used to determine the plural form.
+ If no message catalog is found @a origString is returned if 'n == 1',
+ otherwise @a origString2.
+
+ See GNU gettext manual for additional information on plural forms handling.
+ This method is called by the wxGetTranslation() function and _() macro.
+
+ @remarks Domains are searched in the last to first order, i.e. catalogs
+ added later override those added before.
+ */
+ const wxString& GetString(const wxString& origString,
+ const wxString& origString2,
+ size_t n,
+ const wxString& domain = wxEmptyString) const;
+
+ /**
+ Returns the header value for header @a header.
+ The search for @a header is case sensitive. If an @a domain is passed,
+ this domain is searched. Else all domains will be searched until a
+ header has been found.
+
+ The return value is the value of the header if found. Else this will be empty.
+ */
+ wxString GetHeaderValue(const wxString& header,
+ const wxString& domain = wxEmptyString) const;
+};
+
+
+/**
+ Abstraction of translations discovery and loading.
+
+ This interface makes it possible to override wxWidgets' default catalogs
+ loading mechanism and load MO files from locations other than the
+ filesystem (e.g. embed them in executable).
+
+ Implementations must implement the LoadCatalog() method.
+
+ @see wxFileTranslationsLoader
+ */
+class wxTranslationsLoader
+{
+public:
+ /// Constructor
+ wxTranslationsLoader() {}
+
+ /**
+ Called to load requested catalog.
+
+ If the catalog is found, LoadCatalog() should call LoadCatalogFile()
+ on @a translations to add the translation.
+
+ @param translations wxTranslations requesting loading.
+ @param domain Domain to load.
+ @param lang Language to look for. This is "canonical name"
+ (see wxLocale::GetCanonicalName()), i.e. ISO 639
+ code, possibly combined with country code or
+ additional modifiers (e.g. "fr", "en_GB" or
+ "ca@valencia").
+
+ @return @true on successful load, @false otherwise
+ */
+ virtual bool LoadCatalog(wxTranslations *translations,
+ const wxString& domain, const wxString& lang) = 0;
+};
+
+/**
+ Standard wxTranslationsLoader implementation.
+
+ This finds catalogs in the filesystem, using the standard Unix layout.
+ This is the default unless you change the loader with
+ wxTranslations::SetLoader().
+
+ Catalogs are searched for in standard places (current directory first, then
+ the system one), but you may also prepend additional directories to the
+ search path with AddCatalogLookupPathPrefix().
+ */
+class wxFileTranslationsLoader : public wxTranslationsLoader
+{
+public:
+ /**
+ Add a prefix to the catalog lookup path: the message catalog files will
+ be looked up under prefix/lang/LC_MESSAGES, prefix/lang and prefix
+ (in this order).
+
+ This only applies to subsequent invocations of
+ wxTranslations::AddCatalog().
+ */
+ static void AddCatalogLookupPathPrefix(const wxString& prefix);
+};
+
+
+
+// ============================================================================
+// Global functions/macros
+// ============================================================================
+
+/** @addtogroup group_funcmacro_string */
+//@{
+
+/**
+ This macro is identical to _() but for the plural variant of
+ wxGetTranslation().
+
+ @return A const wxString.
+
+ @header{wx/intl.h}
+*/
+#define wxPLURAL(string, plural, n)
+
+/**
+ This macro doesn't do anything in the program code -- it simply expands to
+ the value of its argument.
+
+ However it does have a purpose which is to mark the literal strings for the
+ extraction into the message catalog created by @c xgettext program. Usually
+ this is achieved using _() but that macro not only marks the string for
+ extraction but also expands into a wxGetTranslation() call which means that
+ it cannot be used in some situations, notably for static array
+ initialization.
+
+ Here is an example which should make it more clear: suppose that you have a
+ static array of strings containing the weekday names and which have to be
+ translated (note that it is a bad example, really, as wxDateTime already
+ can be used to get the localized week day names already). If you write:
+
+ @code
+ static const char * const weekdays[] = { _("Mon"), ..., _("Sun") };
+ ...
+ // use weekdays[n] as usual
+ @endcode
+
+ The code wouldn't compile because the function calls are forbidden in the
+ array initializer. So instead you should do this:
+
+ @code
+ static const char * const weekdays[] = { wxTRANSLATE("Mon"), ...,
+ wxTRANSLATE("Sun") };
+ ...
+ // use wxGetTranslation(weekdays[n])
+ @endcode
+
+ Note that although the code @b would compile if you simply omit
+ wxTRANSLATE() in the above, it wouldn't work as expected because there
+ would be no translations for the weekday names in the program message
+ catalog and wxGetTranslation() wouldn't find them.
+
+ @return A const wxChar*.
+
+ @header{wx/intl.h}
+*/
+#define wxTRANSLATE(string)
+
+/**
+ This function returns the translation of @a string in the current
+ @c locale(). If the string is not found in any of the loaded message
+ catalogs (see @ref overview_i18n), the original string is returned. In
+ debug build, an error message is logged -- this should help to find the
+ strings which were not yet translated. If @a domain is specified then only
+ that domain/catalog is searched for a matching string. As this function is
+ used very often, an alternative (and also common in Unix world) syntax is
+ provided: the _() macro is defined to do the same thing as
+ wxGetTranslation().
+
+ This function calls wxTranslations::GetString().
+
+ @note This function is not suitable for literal strings in Unicode builds
+ since the literal strings must be enclosed into _T() or wxT() macro
+ which makes them unrecognised by @c xgettext, and so they are not
+ extracted to the message catalog. Instead, use the _() and wxPLURAL()
+ macro for all literal strings.
+
+ @see wxGetTranslation(const wxString&, const wxString&, size_t, const wxString&)
+
+ @header{wx/intl.h}
+*/
+const wxString& wxGetTranslation(const wxString& string,
+ const wxString& domain = wxEmptyString);
+
+/**
+ This is an overloaded version of
+ wxGetTranslation(const wxString&, const wxString&), please see its
+ documentation for general information.
+
+ This version is used when retrieving translation of string that has
+ different singular and plural forms in English or different plural forms in
+ some other language. Like wxGetTranslation(const wxString&,const wxString&),
+ the @a string parameter must contain the singular form of the string to be
+ converted and is used as the key for the search in the catalog. The
+ @a plural parameter is the plural form (in English). The parameter @a n is
+ used to determine the plural form. If no message catalog is found,
+ @a string is returned if "n == 1", otherwise @a plural is returned.
+
+ See GNU gettext Manual for additional information on plural forms handling:
+ <http://www.gnu.org/software/gettext/manual/gettext.html#Plural-forms>
+ For a shorter alternative see the wxPLURAL() macro.
+
+ This function calls wxLocale::GetString().
+
+ @header{wx/intl.h}
+*/
+const wxString& wxGetTranslation(const wxString& string,
+ const wxString& plural, size_t n,
+ const wxString& domain = wxEmptyString);
+
+/**
+ This macro expands into a call to wxGetTranslation(), so it marks the
+ message for the extraction by @c xgettext just as wxTRANSLATE() does, but
+ also returns the translation of the string for the current locale during
+ execution.
+
+ Don't confuse this with _T()!
+
+ @header{wx/intl.h}
+*/
+const wxString& _(const wxString& string);
+
+//@}
+
projects / wxWidgets.git / blobdiff