#include <wx/translation.h>

Detailed Description

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 also: wxLocale, wxTranslationsLoader, wxFileTranslationsLoader

Public Member Functions
	wxTranslations ()
	Constructor. More...

void	SetLoader (wxTranslationsLoader *loader)
	Changes loader use to read catalogs to a non-default one. More...

void	SetLanguage (wxLanguage lang)
	Sets translations language to use. More...

void	SetLanguage (const wxString &lang)
	Sets translations language to use. More...

wxArrayString	GetAvailableTranslations (const wxString &domain) const
	Returns list of all translations of domain that were found. More...

wxString	GetBestTranslation (const wxString &domain, wxLanguage msgIdLanguage)
	Returns the best UI language for the domain. More...

wxString	GetBestTranslation (const wxString &domain, const wxString &msgIdLanguage="en")
	Returns the best UI language for the domain. More...

bool	AddStdCatalog ()
	Add standard wxWidgets catalogs ("wxstd" and possible port-specific catalogs). More...

bool	AddCatalog (const wxString &domain)
	Add a catalog for use with the current locale. More...

bool	AddCatalog (const wxString &domain, wxLanguage msgIdLanguage)
	Same as AddCatalog(const wxString&), but takes an additional argument, msgIdLanguage. More...

bool	AddCatalog (const wxString &domain, wxLanguage msgIdLanguage, const wxString &msgIdCharset)
	Same as AddCatalog(const wxString&, wxLanguage), but takes two additional arguments, msgIdLanguage and msgIdCharset. More...

bool	IsLoaded (const wxString &domain) const
	Check if the given catalog is loaded, and returns true if it is. More...

const wxString *	GetTranslatedString (const wxString &origString, const wxString &domain=wxEmptyString) const
	Retrieves the translation for a string in all loaded domains unless the domain parameter is specified (and then only this catalog/domain is searched). More...

const wxString *	GetTranslatedString (const wxString &origString, unsigned n, const wxString &domain=wxEmptyString) const
	Retrieves the translation for a string in all loaded domains unless the domain parameter is specified (and then only this catalog/domain is searched). More...

wxString	GetHeaderValue (const wxString &header, const wxString &domain=wxEmptyString) const
	Returns the header value for header header. More...

Static Public Member Functions
static wxTranslations *	Get ()
	Returns current translations object, may return NULL. More...

static void	Set (wxTranslations *t)
	Sets current translations object. More...

Constructor & Destructor Documentation

wxTranslations::wxTranslations ( )

Constructor.

Member Function Documentation

bool wxTranslations::AddCatalog ( const wxString & domain )

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, 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 Writing Non-English Applications.

Returns: 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 wxTranslations::AddCatalog	(	const wxString &	domain,
		wxLanguage	msgIdLanguage
	)

Same as AddCatalog(const wxString&), but takes an additional argument, msgIdLanguage.

Parameters

domain	The catalog domain to add.
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.

Returns: 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 wxTranslations::AddCatalog	(	const wxString &	domain,
		wxLanguage	msgIdLanguage,
		const wxString &	msgIdCharset
	)

Same as AddCatalog(const wxString&, wxLanguage), but takes two additional arguments, msgIdLanguage and msgIdCharset.

This overload is only available in non-Unicode build.

Parameters

domain	The catalog domain to add.
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.
msgIdCharset	Lets you specify the charset used for msgids in sources in case they use 8-bit characters (e.g. German or French strings).

Returns: 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 wxTranslations::AddStdCatalog ( )

Add standard wxWidgets catalogs ("wxstd" and possible port-specific catalogs).

Returns: true if a suitable catalog was found, false otherwise

See also: AddCatalog()

static wxTranslations* wxTranslations::Get ( )

static

Returns current translations object, may return NULL.

You must either call this early in app initialization code, or let wxLocale do it for you.

wxArrayString wxTranslations::GetAvailableTranslations ( const wxString & domain ) const

Returns list of all translations of 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 domain.

See also: GetBestTranslation()

wxString wxTranslations::GetBestTranslation	(	const wxString &	domain,
		wxLanguage	msgIdLanguage
	)

Returns the best UI language for the 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 locale as obtained from wxLocale::GetSystemLanguage(); modern operation systems (Windows Vista+, OS X) have separate language and regional (= locale) settings.

Parameters

domain	The catalog domain to look for.
msgIdLanguage	Specifies the language of "msgid" strings in source code (i.e. arguments to GetString(), wxGetTranslation() and the _() macro).

Returns: Language code if a suitable match was found, empty string otherwise.

Since: 2.9.5

wxString wxTranslations::GetBestTranslation	(	const wxString &	domain,
		const wxString &	msgIdLanguage = `"en"`
	)

Returns the best UI language for the 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 locale as obtained from wxLocale::GetSystemLanguage(); modern operation systems (Windows Vista+, OS X) have separate language and regional (= locale) settings.

Parameters

domain	The catalog domain to look for.
msgIdLanguage	Specifies the language of "msgid" strings in source code (i.e. arguments to GetString(), wxGetTranslation() and the _() macro).

Returns: Language code if a suitable match was found, empty string otherwise.

Since: 2.9.5

wxString wxTranslations::GetHeaderValue	(	const wxString &	header,
		const wxString &	domain = `wxEmptyString`
	)		const

Returns the header value for header header.

The search for header is case sensitive. If an 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.

const wxString* wxTranslations::GetTranslatedString	(	const wxString &	origString,
		const wxString &	domain = `wxEmptyString`
	)		const

Retrieves the translation for a string in all loaded domains unless the domain parameter is specified (and then only this catalog/domain is searched).

Returns NULL if translation is not available.

This function is thread-safe.

Remarks: Domains are searched in the last to first order, i.e. catalogs added later override those added before.

Since: 3.0

const wxString* wxTranslations::GetTranslatedString	(	const wxString &	origString,
		unsigned	n,
		const wxString &	domain = `wxEmptyString`
	)		const

Retrieves the translation for a string in all loaded domains unless the domain parameter is specified (and then only this catalog/domain is searched).

Returns NULL if translation is not available.

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.

Parameters

origString	The singular form of the string to be converted.
n	The number on which the plural form choice depends on. (In some languages, there are different plural forms for e.g. n=2 and n=3 etc., in addition to the singular form (n=1) being different.)
domain	The only domain (i.e. message catalog) to search if specified. By default this parameter is empty, indicating that all loaded catalogs should be searched.

See GNU gettext manual for additional information on plural forms handling. This method is called by the wxGetTranslation() function and _() macro.

This function is thread-safe.

Remarks: Domains are searched in the last to first order, i.e. catalogs added later override those added before.

Since: 3.0

bool wxTranslations::IsLoaded ( const wxString & domain ) const

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 also: AddCatalog()

static void wxTranslations::Set ( wxTranslations * t )

static

Sets current translations object.

Deletes previous translation object and takes ownership of t.

void wxTranslations::SetLanguage ( wxLanguage lang )

Sets translations language to use.

wxLANGUAGE_DEFAULT has special meaning: best suitable translation, given user's preference and available translations, will be used.

void wxTranslations::SetLanguage ( const wxString & lang )

Sets translations language to use.

Empty 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 wxTranslations::SetLoader ( wxTranslationsLoader * loader )

Changes loader use to read catalogs to a non-default one.

Deletes previous loader and takes ownership of loader.

See also: wxTranslationsLoader, wxFileTranslationsLoader, wxResourceTranslationsLoader

Detailed Description

Public Member Functions

Static Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation