// 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
{
*/
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).
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
*/
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
This class is only available on Windows.
@since 2.9.1
-
*/
class wxResourceTranslationsLoader : public wxTranslationsLoader
{
};
+/**
+ 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);
+};
+
// ============================================================================
// Global functions/macros
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&, unsigned, const wxString&)
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