X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7ed63042c662c403fac98e5b25800853777382d3..9e9574fe45b176ee74bba8fad7574cf9906145d1:/interface/wx/translation.h diff --git a/interface/wx/translation.h b/interface/wx/translation.h index cec4db149a..dcd46bed10 100644 --- a/interface/wx/translation.h +++ b/interface/wx/translation.h @@ -2,8 +2,7 @@ // Name: translation.h // Purpose: wxTranslation class // Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// @@ -30,7 +29,7 @@ @since 2.9.1 - @see wxLocale + @see wxLocale, wxTranslationsLoader, wxFileTranslationsLoader */ class wxTranslations { @@ -58,7 +57,7 @@ public: Deletes previous loader and takes ownership of @a loader. - @see wxTranslationsLoader, wxFileTranslationsLoader + @see wxTranslationsLoader, wxFileTranslationsLoader, wxResourceTranslationsLoader */ void SetLoader(wxTranslationsLoader *loader); @@ -79,6 +78,64 @@ public: */ void SetLanguage(const wxString& lang); + /** + Returns list of all translations of @a domain that were found. + + This method can be used e.g. to populate list of application's + translations offered to the user. To do this, pass the app's main + catalog as @a domain. + + @see GetBestTranslation() + */ + wxArrayString GetAvailableTranslations(const wxString& domain) const; + + /** + Returns the best UI language for the @a domain. + + The language is determined from the preferred UI language or languages + list the user configured in the OS. Notice that this may or may not + correspond to the default @em locale as obtained from + wxLocale::GetSystemLanguage(); modern operation systems (Windows + Vista+, OS X) have separate language and regional (= locale) settings. + + @param domain + The catalog domain to look for. + + @param msgIdLanguage + Specifies the language of "msgid" strings in source code + (i.e. arguments to GetString(), wxGetTranslation() and the _() macro). + + @return Language code if a suitable match was found, empty string + otherwise. + + @since 2.9.5 + */ + wxString GetBestTranslation(const wxString& domain, wxLanguage msgIdLanguage); + + /** + Returns the best UI language for the @a domain. + + The language is determined from the preferred UI language or languages + list the user configured in the OS. Notice that this may or may not + correspond to the default @em locale as obtained from + wxLocale::GetSystemLanguage(); modern operation systems (Windows + Vista+, OS X) have separate language and regional (= locale) settings. + + @param domain + The catalog domain to look for. + + @param msgIdLanguage + Specifies the language of "msgid" strings in source code + (i.e. arguments to GetString(), wxGetTranslation() and the _() macro). + + @return Language code if a suitable match was found, empty string + otherwise. + + @since 2.9.5 + */ + wxString GetBestTranslation(const wxString& domain, + const wxString& msgIdLanguage = "en"); + /** Add standard wxWidgets catalogs ("wxstd" and possible port-specific catalogs). @@ -169,20 +226,6 @@ public: */ 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). @@ -226,7 +269,7 @@ public: */ const wxString& GetString(const wxString& origString, const wxString& origString2, - size_t n, + unsigned n, const wxString& domain = wxEmptyString) const; /** @@ -251,23 +294,23 @@ public: Implementations must implement the LoadCatalog() method. - @see wxFileTranslationsLoader + @see wxFileTranslationsLoader, wxResourceTranslationsLoader @since 2.9.1 */ class wxTranslationsLoader { public: - /// Constructor - wxTranslationsLoader() {} + /// Trivial default constructor. + wxTranslationsLoader(); /** Called to load requested catalog. - If the catalog is found, LoadCatalog() should call LoadCatalogFile() - on @a translations to add the translation. + If the catalog is found, LoadCatalog() should create wxMsgCatalog + instance with its data and return it. The caller will take ownership + of the catalog. - @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 @@ -275,10 +318,15 @@ public: additional modifiers (e.g. "fr", "en_GB" or "ca@valencia"). - @return @true on successful load, @false otherwise + @return Loaded catalog or NULL on failure. + */ + virtual wxMsgCatalog *LoadCatalog(const wxString& domain, + const wxString& lang) = 0; + + /** + Implements wxTranslations::GetAvailableTranslations(). */ - virtual bool LoadCatalog(wxTranslations *translations, - const wxString& domain, const wxString& lang) = 0; + virtual wxArrayString GetAvailableTranslations(const wxString& domain) const = 0; }; /** @@ -288,9 +336,11 @@ public: 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(). + Catalogs are searched for in standard places (system locales directory, + `LC_PATH` on Unix systems, Resources subdirectory of the application bundle + on OS X, executable's directory on Windows), but you may also prepend + additional directories to the search path with + AddCatalogLookupPathPrefix(). @since 2.9.1 */ @@ -299,7 +349,7 @@ 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 + be looked up under prefix/lang/LC_MESSAGES and prefix/lang directories (in this order). This only applies to subsequent invocations of @@ -308,6 +358,88 @@ public: static void AddCatalogLookupPathPrefix(const wxString& prefix); }; +/** + This loader makes it possible to load translations from Windows + resources. + + If you wish to store translation MO files in resources, you have to + enable this loader before calling wxTranslations::AddCatalog() or + wxLocale::AddCatalog(): + + @code + wxTranslations::Get()->SetLoader(new wxResourceTranslationsLoader); + @endcode + + Translations are stored in resources as compiled MO files, with type + set to "MOFILE" (unless you override GetResourceType()) and name + consisting of the domain, followed by underscore, followed by language + identification. For example, the relevant part of .rc file would look + like this: + + @code + myapp_de MOFILE "catalogs/de/myapp.mo" + myapp_fr MOFILE "catalogs/fr/myapp.mo" + myapp_en_GB MOFILE "catalogs/en_GB/myapp.mo" + @endcode + + This class is only available on Windows. + + @since 2.9.1 + */ +class wxResourceTranslationsLoader : public wxTranslationsLoader +{ +protected: + /** + Returns resource type to use for translations. + + Default type is "MOFILE". + */ + virtual wxString GetResourceType() const; + + /** + Returns handle of the module to load resources from. + + By default, the main executable is used. + */ + virtual WXHINSTANCE GetModule() const; +}; + + +/** + Represents a loaded translations message catalog. + + This class should only be used directly by wxTranslationsLoader + implementations. + + @since 2.9.1 + */ +class wxMsgCatalog +{ +public: + /** + Creates catalog loaded from a MO file. + + @param filename Path to the MO file to load. + @param domain Catalog's domain. This typically matches + the @a filename. + + @return Successfully loaded catalog or NULL on failure. + */ + static wxMsgCatalog *CreateFromFile(const wxString& filename, + const wxString& domain); + + /** + Creates catalog from MO file data in memory buffer. + + @param data Data in MO file format. + @param domain Catalog's domain. This typically matches + the @a filename. + + @return Successfully loaded catalog or NULL on failure. + */ + static wxMsgCatalog *CreateFromData(const wxScopedCharBuffer& data, + const wxString& domain); +}; // ============================================================================ @@ -384,12 +516,12 @@ public: 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. + since the literal strings must be enclosed in 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&) + @see wxGetTranslation(const wxString&, const wxString&, unsigned, const wxString&) @header{wx/intl.h} */ @@ -419,17 +551,17 @@ const wxString& wxGetTranslation(const wxString& string, @header{wx/intl.h} */ const wxString& wxGetTranslation(const wxString& string, - const wxString& plural, size_t n, + const wxString& plural, unsigned n, const wxString& domain = wxEmptyString); /** + Macro to be used around all literal strings that should be translated. + 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);