| Version: 3.3.1

Public Member Functions | Static Public Member Functions | List of all members
wxTranslations Class Reference

`#include <wx/translation.h>`

## Detailed Description

This class allows getting translations for strings.

In wxWidgets, this class manages message catalogs which contain the translations of the strings used for the current language. Only one wxTranslations instance is active at a time; it is set with the Set() method and obtained using Get().

wxTranslations's 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 languages not recognized by the operating system or not listed in the wxLanguage enum.

This class works in conjunction with wxUILocale. While calling wxUILocale::UseDefault() can inform the program of how to format numbers and such (see wxNumberFormatter), wxTranslations offers the ability to load translations separate from the locale. In other words, the program can respect the user's regional formatting while providing them a choice different display languages.

Note that this class is used by wxLocale internally; the use of wxLocale is, however, no longer recommended. Rather, it is recommended to use wxTranslations and wxUILocale together for managing translations and regional settings.

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 | GetBestAvailableTranslation (const wxString &domain)
| Returns the best available translation for the required language. 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")
| This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...
bool | AddStdCatalog ()
| Add standard wxWidgets catalogs ("wxstd" and possible port-specific catalogs). More...
bool | AddAvailableCatalog (const wxString &domain, wxLanguage msgIdLanguage=wxLANGUAGE_ENGLISH_US)
| Add a catalog for use with the current locale. More...
bool | AddCatalog (const wxString &domain, wxLanguage msgIdLanguage=wxLANGUAGE_ENGLISH_US)
| Add a catalog for use with the current locale or fall back to the original messages language. 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 nullptr. More...
static void | Set (wxTranslations *t)
| Sets current translations object. More...

## Constructor & Destructor Documentation

## ◆ wxTranslations()

wxTranslations::wxTranslations | ( |  | ) |

Constructor.

## Member Function Documentation

## ◆ AddAvailableCatalog()

bool wxTranslations::AddAvailableCatalog | ( | const wxString & | domain,
|  | wxLanguage | msgIdLanguage = `wxLANGUAGE_ENGLISH_US`
| ) |  |

Add a catalog for use with the current locale.

By default, the catalog 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.

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, usually because it wasn't found. Note that unlike AddCatalog() this function returns false even if the language of the original strings (usually English) can be used directly, i.e. its return value only indicates that there are no catalogs available for the selected or system-default languages, but is not necessarily an error if no translations are needed in the first place.

Since
  3.2.5

## ◆ AddCatalog()

bool wxTranslations::AddCatalog | ( | const wxString & | domain,
|  | wxLanguage | msgIdLanguage = `wxLANGUAGE_ENGLISH_US`
| ) |  |

Add a catalog for use with the current locale or fall back to the original messages language.

This function behaves like AddAvailableCatalog() but also checks if the strings used in the program, written in msgIdLanguage, can be used without any translations on the current system and also returns true in this case, unlike AddAvailableCatalog().

By default, i.e. if msgIdLanguage is not given, `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.

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 or loading it is unnecessary because the original messages can be used directly, false otherwise (which might mean that the catalog is not found or that it isn't in the correct format).

## ◆ AddStdCatalog()

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
  AddAvailableCatalog()

Note
  For client systems that may not have wxWidget message catalogs installed (e.g., Windows), be sure to include your own copy of various "wxstd.mo" files with your distributions. For example, you can do the following for Spanish:
  - compile "locale/es.po" into a *.mo file
  - rename it "wxstd.mo"
  - include it with your program in a folder named "es"

## ◆ Get()

static wxTranslations* wxTranslations::Get | ( |  | ) |
| static

Returns current translations object, may return nullptr.

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

## ◆ GetAvailableTranslations()

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.

Note
  The returned list does not include messages ID language, i.e. the language (typically English) included in the source code. In the use case described above, that language needs to be added manually.

See also
  GetBestTranslation()

## ◆ GetBestAvailableTranslation()

wxString wxTranslations::GetBestAvailableTranslation | ( | const wxString & | domain | ) |

Returns the best available translation for the required language.

For `wxLANGUAGE_DEFAULT`, this function returns the available translation best matching one of wxUILocale::GetPreferredUILanguages(). Otherwise it simply returns the language set with SetLanguage() if it's available or empty string otherwise.

Warning
  This function does not consider messages ID language (typically English) and can return inappropriate language if it is anywhere in user's preferred languages list. Use GetBestTranslation() instead unless you have very specific needs.

Since
  3.3.0

## ◆ GetBestTranslation() [1/2]

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

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

## ◆ GetBestTranslation() [2/2]

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() as operating systems have separate language and regional (i.e. locale) settings.

Please note that that this function may return the language corresponding to msgIdLanguage if this language is considered to be acceptable, i.e. is part of wxUILocale::GetPreferredUILanguages(), indicating that it is fine not to use translations at all on this system. If this is undesirable, GetBestAvailableTranslation() should be used which doesn't consider the messages ID language as being available.

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

## ◆ GetHeaderValue()

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 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.

## ◆ GetTranslatedString() [1/2]

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 nullptr 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

## ◆ GetTranslatedString() [2/2]

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 nullptr 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

## ◆ IsLoaded()

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
  AddAvailableCatalog()

## ◆ Set()

static void wxTranslations::Set | ( | wxTranslations * | t | ) |
| static

Sets current translations object.

Deletes previous translation object and takes ownership of t.

## ◆ SetLanguage() [1/2]

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.

## ◆ SetLanguage() [2/2]

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.

## ◆ SetLoader()

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