// Name: translation.h
// Purpose: wxTranslation class
// Author: wxWidgets team
-// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
@since 2.9.1
- @see wxLocale
+ @see wxLocale, wxTranslationsLoader, wxFileTranslationsLoader
*/
class wxTranslations
{
Deletes previous loader and takes ownership of @a loader.
- @see wxTranslationsLoader, wxFileTranslationsLoader
+ @see wxTranslationsLoader, wxFileTranslationsLoader, wxResourceTranslationsLoader
*/
void SetLoader(wxTranslationsLoader *loader);
*/
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).
*/
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).
*/
const wxString& GetString(const wxString& origString,
const wxString& origString2,
- size_t n,
+ unsigned n,
const wxString& domain = wxEmptyString) const;
/**
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
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;
};
/**
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
*/
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
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);
+};
// ============================================================================
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}
*/
@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);
projects / wxWidgets.git / blobdiff