Split wxLocale into wxLocale and wxTranslations.

wxTranslations is for handling gettext translations. wxLocale manages
locale and provides compatiblity API for translations. Separating these
two loosely related tasks makes it possible to use translations into
languages not known by Windows or using localized GUI without all the
locales compilations.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@64117 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/changes.txt

@@ -445,6 +445,7 @@ All:
 - Correct wxSocket::Peek() to not block (Anders Larsen).
 - Added IEC and SI units support to GetHumanReadableSize() (Julien Weinzorn).
 - Add convenient wxString::ToStd{String,Wstring}() helpers.
+- Added wxTranslations class to allow localization without changing locale.
 
 Unix:
 

include/wx/intl.h

@@ -19,6 +19,10 @@
 #include "wx/defs.h"
 #include "wx/string.h"
 
+#if !wxUSE_UNICODE
+    #include "wx/hashmap.h"
+#endif
+
 // Make wxLayoutDirection enum available without need for wxUSE_INTL so wxWindow, wxApp
 // and other classes are not distrubed by wxUSE_INTL
 
@@ -57,6 +61,7 @@ enum wxLayoutDirection
 // forward decls
 // ----------------------------------------------------------------------------
 
+class WXDLLIMPEXP_FWD_BASE wxTranslationsLoader;
 class WXDLLIMPEXP_FWD_BASE wxLocale;
 class WXDLLIMPEXP_FWD_BASE wxLanguageInfoArray;
 class wxMsgCatalog;
@@ -355,6 +360,111 @@ struct WXDLLIMPEXP_BASE wxLanguageInfo
 inline wxString wxLanguageInfo::GetLocaleName() const { return CanonicalName; }
 #endif // !__WXMSW__
 
+// ----------------------------------------------------------------------------
+// wxTranslations: message catalogs
+// ----------------------------------------------------------------------------
+
+// this class allows to get translations for strings
+class WXDLLIMPEXP_BASE wxTranslations
+{
+public:
+    wxTranslations();
+    ~wxTranslations();
+
+    // returns current translations object, may return NULL
+    static wxTranslations *Get();
+    // sets current translations object (takes ownership; may be NULL)
+    static void Set(wxTranslations *t);
+
+    // changes loader to non-default one; takes ownership of 'loader'
+    void SetLoader(wxTranslationsLoader *loader);
+
+    void SetLanguage(wxLanguage lang);
+    void SetLanguage(const wxString& lang);
+
+    // add standard wxWidgets catalog ("wxstd")
+    bool AddStdCatalog();
+
+    // add catalog with given domain name and language, looking it up via
+    // wxTranslationsLoader
+    bool AddCatalog(const wxString& domain);
+    bool AddCatalog(const wxString& domain, wxLanguage msgIdLanguage);
+#if !wxUSE_UNICODE
+    bool AddCatalog(const wxString& domain,
+                    wxLanguage msgIdLanguage,
+                    const wxString& msgIdCharset);
+#endif
+
+    // check if the given catalog is loaded
+    bool IsLoaded(const wxString& domain) const;
+
+    // load catalog data directly from file
+    bool LoadCatalogFile(const wxString& filename,
+                         const wxString& domain = wxEmptyString);
+
+    // access to translations
+    const wxString& GetString(const wxString& origString,
+                              const wxString& domain = wxEmptyString) const;
+    const wxString& GetString(const wxString& origString,
+                              const wxString& origString2,
+                              size_t n,
+                              const wxString& domain = wxEmptyString) const;
+
+    wxString GetHeaderValue(const wxString& header,
+                            const wxString& domain = wxEmptyString) const;
+
+    // this is hack to work around a problem with wxGetTranslation() which
+    // returns const wxString& and not wxString, so when it returns untranslated
+    // string, it needs to have a copy of it somewhere
+    static const wxString& GetUntranslatedString(const wxString& str);
+
+private:
+    // find best translation for given domain
+    wxString ChooseLanguageForDomain(const wxString& domain,
+                                     const wxString& msgIdLang);
+
+    // find catalog by name in a linked list, return NULL if !found
+    wxMsgCatalog *FindCatalog(const wxString& domain) const;
+
+    // same as Set(), without taking ownership; only for wxLocale
+    static void SetNonOwned(wxTranslations *t);
+    friend class wxLocale;
+
+private:
+    wxString m_lang;
+    wxTranslationsLoader *m_loader;
+
+    wxMsgCatalog *m_pMsgCat; // pointer to linked list of catalogs
+
+#if !wxUSE_UNICODE
+    wxStringToStringHashMap m_msgIdCharset;
+#endif
+};
+
+
+// abstraction of translations discovery and loading
+class WXDLLIMPEXP_BASE wxTranslationsLoader
+{
+public:
+    wxTranslationsLoader() {}
+    virtual ~wxTranslationsLoader() {}
+
+    virtual bool LoadCatalog(wxTranslations *translations,
+                             const wxString& domain, const wxString& lang) = 0;
+};
+
+// standard wxTranslationsLoader implementation, using filesystem
+class WXDLLIMPEXP_BASE wxFileTranslationsLoader
+    : public wxTranslationsLoader
+{
+public:
+    static void AddCatalogLookupPathPrefix(const wxString& prefix);
+
+    virtual bool LoadCatalog(wxTranslations *translations,
+                             const wxString& domain, const wxString& lang);
+};
+
+
 // ----------------------------------------------------------------------------
 // wxLocaleCategory: the category of locale settings
 // ----------------------------------------------------------------------------
@@ -508,7 +618,8 @@ public:
     // (in this order).
     //
     // This only applies to subsequent invocations of AddCatalog()!
-    static void AddCatalogLookupPathPrefix(const wxString& prefix);
+    static void AddCatalogLookupPathPrefix(const wxString& prefix)
+        { wxFileTranslationsLoader::AddCatalogLookupPathPrefix(prefix); }
 
     // add a catalog: it's searched for in standard places (current directory
     // first, system one after), but the you may prepend additional directories to
@@ -517,7 +628,10 @@ public:
     // The loaded catalog will be used for message lookup by GetString().
     //
     // Returns 'true' if it was successfully loaded
-    bool AddCatalog(const wxString& domain);
+    bool AddCatalog(const wxString& domain)
+        { return m_translations.AddCatalog(domain); }
+    bool AddCatalog(const wxString& domain, wxLanguage msgIdLanguage)
+        { return m_translations.AddCatalog(domain, msgIdLanguage); }
     bool AddCatalog(const wxString& domain,
                     wxLanguage msgIdLanguage, const wxString& msgIdCharset);
 
@@ -525,7 +639,8 @@ public:
     static bool IsAvailable(int lang);
 
     // check if the given catalog is loaded
-    bool IsLoaded(const wxString& domain) const;
+    bool IsLoaded(const wxString& domain) const
+        { return m_translations.IsLoaded(domain); }
 
     // Retrieve the language info struct for the given language
     //
@@ -536,6 +651,10 @@ public:
     // is not in database
     static wxString GetLanguageName(int lang);
 
+    // Returns ISO code ("canonical name") of language or empty string if the
+    // language is not in database
+    static wxString GetLanguageCanonicalName(int lang);
+
     // Find the language for the given locale string which may be either a
     // canonical ISO 2 letter language code ("xx"), a language code followed by
     // the country code ("xx_XX") or a Windows full language name ("Xxxxx...")
@@ -559,25 +678,35 @@ public:
     //
     // domains are searched in the last to first order, i.e. catalogs
     // added later override those added before.
-    virtual const wxString& GetString(const wxString& origString,
+    const wxString& GetString(const wxString& origString,
-                                      const wxString& domain = wxEmptyString) const;
+                              const wxString& domain = wxEmptyString) const
+    {
+        return m_translations.GetString(origString, domain);
+    }
     // plural form version of the same:
-    virtual const wxString& GetString(const wxString& origString,
+    const wxString& GetString(const wxString& origString,
-                                      const wxString& origString2,
+                              const wxString& origString2,
-                                      size_t n,
+                              size_t n,
-                                      const wxString& domain = wxEmptyString) const;
+                              const wxString& domain = wxEmptyString) const
+    {
+        return m_translations.GetString(origString, origString2, n, domain);
+    }
 
     // this is hack to work around a problem with wxGetTranslation() which
     // returns const wxString& and not wxString, so when it returns untranslated
     // string, it needs to have a copy of it somewhere
-    static const wxString& GetUntranslatedString(const wxString& str);
+    static const wxString& GetUntranslatedString(const wxString& str)
+        { return wxTranslations::GetUntranslatedString(str); }
 
     // Returns the current short name for the locale
     const wxString& GetName() const { return m_strShort; }
 
     // return the contents of .po file header
     wxString GetHeaderValue(const wxString& header,
-                            const wxString& domain = wxEmptyString) const;
+                            const wxString& domain = wxEmptyString) const
+    {
+        return m_translations.GetHeaderValue(header, domain);
+    }
 
     // These two methods are for internal use only. First one creates
     // ms_languagesDB if it doesn't already exist, second one destroys
@@ -586,8 +715,9 @@ public:
     static void DestroyLanguagesDB();
 
 private:
-    // find catalog by name in a linked list, return NULL if !found
+    bool DoInit(const wxString& name,
-    wxMsgCatalog *FindCatalog(const wxString& domain) const;
+                const wxString& shortName,
+                const wxString& locale);
 
     // copy default table of languages from global static array to
     // m_langugagesInfo, called by InitLanguagesDB
@@ -603,10 +733,10 @@ private:
     const char  *m_pszOldLocale;      // previous locale from setlocale()
     wxLocale      *m_pOldLocale;      // previous wxLocale
 
-    wxMsgCatalog  *m_pMsgCat;         // pointer to linked list of catalogs
-
     bool           m_initialized;
 
+    wxTranslations m_translations;
+
     static wxLanguageInfoArray *ms_languagesDB;
 
     wxDECLARE_NO_COPY_CLASS(wxLocale);
@@ -623,28 +753,28 @@ extern WXDLLIMPEXP_BASE wxLocale* wxGetLocale();
 inline const wxString& wxGetTranslation(const wxString& str,
                                         const wxString& domain = wxEmptyString)
 {
-    wxLocale *pLoc = wxGetLocale();
+    wxTranslations *trans = wxTranslations::Get();
-    if (pLoc)
+    if ( trans )
-        return pLoc->GetString(str, domain);
+        return trans->GetString(str, domain);
     else
         // NB: this function returns reference to a string, so we have to keep
         //     a copy of it somewhere
-        return wxLocale::GetUntranslatedString(str);
+        return wxTranslations::GetUntranslatedString(str);
 }
 inline const wxString& wxGetTranslation(const wxString& str1,
                                         const wxString& str2,
                                         size_t n,
                                         const wxString& domain = wxEmptyString)
 {
-    wxLocale *pLoc = wxGetLocale();
+    wxTranslations *trans = wxTranslations::Get();
-    if (pLoc)
+    if ( trans )
-        return pLoc->GetString(str1, str2, n, domain);
+        return trans->GetString(str1, str2, n, domain);
     else
         // NB: this function returns reference to a string, so we have to keep
         //     a copy of it somewhere
         return n == 1
-               ? wxLocale::GetUntranslatedString(str1)
+               ? wxTranslations::GetUntranslatedString(str1)
-               : wxLocale::GetUntranslatedString(str2);
+               : wxTranslations::GetUntranslatedString(str2);
 }
 
 #else // !wxUSE_INTL

interface/wx/intl.h

@@ -419,8 +419,8 @@ enum wxLocaleInfo
     wxLocale class encapsulates all language-dependent settings and is a
     generalization of the C locale concept.
 
-    In wxWidgets this class manages message catalogs which contain the translations
+    In wxWidgets this class manages current locale. It also initializes and
-    of the strings used to the current language.
+    activates wxTranslations object that manages message catalogs.
 
     For a list of the supported languages, please see ::wxLanguage enum values.
     These constants may be used to specify the language in wxLocale::Init and
@@ -465,7 +465,7 @@ enum wxLocaleInfo
     @library{wxbase}
     @category{cfg}
 
-    @see @ref overview_i18n, @ref page_samples_internat, wxXLocale
+    @see @ref overview_i18n, @ref page_samples_internat, wxXLocale, wxTranslations
 */
 class wxLocale
 {
@@ -504,64 +504,23 @@ public:
     virtual ~wxLocale();
 
     /**
-        Add a catalog for use with the current locale: it is searched for in standard
+        Calls wxTranslations::AddCatalog(const wxString&).
-        places (current directory first, then the system one), but you may also prepend
-        additional directories to the search path with 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);
 
     /**
-        Add a catalog for use with the current locale: it is searched for in standard
+        Calls wxTranslations::AddCatalog(const wxString&, wxLanguage).
-        places (current directory first, then the system one), but you may also prepend
+    */
-        additional directories to the search path with AddCatalogLookupPathPrefix().
+    bool AddCatalog(const wxString& domain, wxLanguage msgIdLanguage);
 
-        All loaded catalogs will be used for message lookup by GetString() for
+    /**
-        the current locale.
+        Calls wxTranslations::AddCatalog(const wxString&, wxLanguage, const wxString&).
-
-        This overload takes two additional arguments, @a msgIdLanguage and @a msgIdCharset.
-
-        @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).
-            This argument has no effect in Unicode build, because literals in sources are
-            Unicode strings; you have to use compiler-specific method of setting the right
-            charset when compiling with Unicode.
-
-        @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);
 
     /**
-        Add a prefix to the catalog lookup path: the message catalog files will
+        Calls wxFileTranslationsLoader::AddCatalogLookupPathPrefix().
-        be looked up under prefix/lang/LC_MESSAGES, prefix/lang and prefix
-        (in this order).
-
-        This only applies to subsequent invocations of AddCatalog().
     */
     static void AddCatalogLookupPathPrefix(const wxString& prefix);
 
@@ -596,12 +555,7 @@ public:
     wxString GetCanonicalName() const;
 
     /**
-        Returns the header value for header @a header.
+        Calls wxTranslations::GetHeaderValue().
-        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;
@@ -634,6 +588,16 @@ public:
     */
     static wxString GetLanguageName(int lang);
 
+    /**
+        Returns canonical name (see GetCanonicalName()) of the given language
+        or empty string if this language is unknown.
+
+        See GetLanguageInfo() for a remark about special meaning of @c wxLANGUAGE_DEFAULT.
+
+        @since 2.9.1
+    */
+    static wxString GetLanguageCanonicalName(int lang);
+
     /**
         Returns the locale name as passed to the constructor or Init().
 
@@ -648,45 +612,13 @@ public:
     const wxString& GetName() const;
 
     /**
-        Retrieves the translation for a string in all loaded domains unless the @a domain
+        Calls wxTranslations::GetString(const wxString&, const wxString&) const.
-        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.
     */
     virtual 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
+        Calls wxTranslations::GetString(const wxString&, const wxString&, size_t, const wxString&) const.
-        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.
     */
     virtual const wxString& GetString(const wxString& origString,
                                       const wxString& origString2, size_t n,
@@ -803,12 +735,7 @@ public:
     static bool IsAvailable(int lang);
 
     /**
-        Check if the given catalog is loaded, and returns @true if it is.
+        Calls wxTranslations::IsLoaded().
-
-        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;
 
@@ -819,6 +746,303 @@ public:
 };
 
 
+/**
+    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);
+};
+
 
 
 // ============================================================================
@@ -892,7 +1116,7 @@ public:
     provided: the _() macro is defined to do the same thing as
     wxGetTranslation().
 
-    This function calls wxLocale::GetString().
+    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