FlightGear: FGTranslate Class Reference

Class for retrieving translated strings. More...

#include <FGTranslate.hxx>

Public Types
using	intType = flightgear::LanguageInfo::intType

Public Member Functions
	FGTranslate (const std::string &domain="core")
	Constructor.

FGTranslate &	setDomain (const std::string &domain)
	Change the domain from which to retrieve translations.

flightgear::TranslationDomain::ResourceRef	getResource (const std::string &resourceName) const
	Get the specified resource.

std::string	get (const std::string &resource, const std::string &basicId, int index=0) const
	Get a single translation.

std::string	getPlural (intType cardinalNumber, const std::string &resource, const std::string &basicId, int index=0) const
	Same as get(), but for a string that has plural forms.

std::string	getWithDefault (const std::string &resource, const std::string &basicId, const std::string &defaultValue, int index=0) const
	Get a single translation, with default for missing or empty strings.

std::string	getPluralWithDefault (intType cardinalNumber, const std::string &resource, const std::string &basicId, const std::string &defaultValue, int index=0) const
	Same as getWithDefault(), but for a string that has plural forms.

std::vector< std::string >	getAll (const std::string &resource, const std::string &basicId) const
	Get all translations associated to an id (tag name).

std::size_t	getCount (const std::string &resource, const std::string &basicId) const
	Get the number of translatable strings with a given id (tag name).

std::shared_ptr< TranslationUnit >	translationUnit (const std::string &resource, const std::string &basicId, int index=0) const
	Return a shared pointer to a TranslationUnit.

Static Public Member Functions
static void	setupGhost ()
	Set up a Nasal type that wraps FGTranslate.

Detailed Description

Class for retrieving translated strings.

The defaut domain is “core”; it corresponds to translations defined in FGData. Other domains are “current-aircraft” and “addons/⟨addonId⟩”.

If the translatable string specified by the (domain, resource, basicId, index) tuple doesn't have has-plural="true" in the default translation, it is a string with no plural forms. Member functions get() and getWithDefault() are appropriate for retrieving translations of such strings. On the other hand, if a translatable string is defined with has-plural="true" in the default translation, it has plural forms. Member functions getPlural() and getPluralWithDefault() are suitable for such strings: they require an additional parmeter (“cardinal number”) which is necessary to choose the correct plural form.

If your code doesn't know in advance whether the string has plural forms, use translationUnit(). With the result, you can query whether the string has plural forms and obtain a translation (see the overloads of TranslationUnit::getTranslation(): one accepts a cardinal number, the other one doesn't). Doing so minimizes the number of lookups for the resource, basicId and index because a TranslationUnit object contains all the information pertaining to a given translatable string.

Examples:

Retrieve the translation of a string defined in FGData that has no plural forms (domain = "core", resource = "options", basicId = "usage", index = 0):

std::string t = FGTranslate().get("options", "usage");

FGTranslate::FGTranslate

FGTranslate(const std::string &domain="core")

Constructor.

Definition FGTranslate.cxx:29

or equivalently:

std::string t = FGTranslate("core").get("options", "usage");

Similar thing but using the second string (index 1) having the id "fg-scenery-desc":

std::string t = FGTranslate().get("options", "fg-scenery-desc", 1);

Similar thing, but fetching the translation from the Skeleton add-on:

std::string t =
  FGTranslate("addons/org.flightgear.addons.Skeleton").get(
    "some-resource", "some-id", 1);

Retrieve a translation with plural forms defined in the current aircraft. Let's assume the translation depends on a number of liveries present in the nbLiveries variable.

std::string t = FGTranslate("current-aircraft").getPlural(

nbLiveries, "some-resource", "some-id");

Definition at line 79 of file FGTranslate.hxx.

Member Typedef Documentation

◆ intType

using FGTranslate::intType = flightgear::LanguageInfo::intType

Definition at line 84 of file FGTranslate.hxx.

Constructor & Destructor Documentation

◆ FGTranslate()

FGTranslate::FGTranslate ( const std::string & domain = "core" )

explicit

Constructor.

Parameters

domain a string such as “core”, “current-aircraft” or “addons/⟨addonId⟩”

The constructed FGTranslate instance will allow retrieving translations from the chosen domain. The domain must already exist when the constructor is called.

Definition at line 29 of file FGTranslate.cxx.

Member Function Documentation

◆ get()

string FGTranslate::get	(	const std::string &	resource,
		const std::string &	basicId,
		int	index = 0 ) const

Get a single translation.

Parameters

resource	resource name, aka “context” (such as "atc", "menu", "sys", etc.) the translatable string belongs to
basicId	name of the XML element corresponding to the translation to retrieve in the default translation file for the specified resource
index	index among strings sharing the same basicId

Returns: The translated string

The translation is fetched from the domain specified with the constructor or with setDomain().

There may be several elements named basicId in the default translation file for the specified resource; these elements are distinguished by their index.

If the resource doesn't exist in the domain or if there is no translatable string with the specified basicId and index in the resource, return an empty string.

Definition at line 63 of file FGTranslate.cxx.

◆ getAll()

std::vector< string > FGTranslate::getAll	(	const std::string &	resource,
		const std::string &	basicId ) const

Get all translations associated to an id (tag name).

Parameters

resource	same as for get()
basicId	same as for get()

Returns: A vector containing all translations with id basicId in the specified resource

Definition at line 114 of file FGTranslate.cxx.

◆ getCount()

std::size_t FGTranslate::getCount	(	const std::string &	resource,
		const std::string &	basicId ) const

Get the number of translatable strings with a given id (tag name).

Parameters

resource	same as for get()
basicId	same as for get()

Returns: The number of elements named basicId in the specified resource (this is the size of the vector that getAll() would return)

Definition at line 126 of file FGTranslate.cxx.

◆ getPlural()

string FGTranslate::getPlural	(	intType	cardinalNumber,
		const std::string &	resource,
		const std::string &	basicId,
		int	index = 0 ) const

Same as get(), but for a string that has plural forms.

Parameters

cardinalNumber	an integer correponding to a number of “things” (concrete or abstract)
resource	same as for get()
basicId	same as for get()
index	same as for get()

Returns: The translated string

Definition at line 75 of file FGTranslate.cxx.

◆ getPluralWithDefault()

string FGTranslate::getPluralWithDefault	(	intType	cardinalNumber,
		const std::string &	resource,
		const std::string &	basicId,
		const std::string &	defaultValue,
		int	index = 0 ) const

Same as getWithDefault(), but for a string that has plural forms.

Parameters

cardinalNumber	an integer correponding to a number of “things” (concrete or abstract)
resource	same as for getWithDefault()
basicId	same as for getWithDefault()
defaultValue	same as for getWithDefault()
index	same as for getWithDefault()

Returns: The translated string or default value

Definition at line 100 of file FGTranslate.cxx.

◆ getResource()

TranslationDomain::ResourceRef FGTranslate::getResource ( const std::string & resourceName ) const

Get the specified resource.

Parameters

resourceName name of the resource

Returns: A shared pointer to the resource

This function logs warnings if the domain or resource can't be found.

Definition at line 41 of file FGTranslate.cxx.

◆ getWithDefault()

string FGTranslate::getWithDefault	(	const std::string &	resource,
		const std::string &	basicId,
		const std::string &	defaultValue,
		int	index = 0 ) const

Get a single translation, with default for missing or empty strings.

Parameters

resource	same as for get()
basicId	same as for get()
defaultValue	returned if the string can't be found or is declared with an empty source text in the default translation
index	same as for get()

Returns: The translated string or default value

Definition at line 87 of file FGTranslate.cxx.

◆ setDomain()

FGTranslate & FGTranslate::setDomain ( const std::string & domain )

Change the domain from which to retrieve translations.

Parameters

domain a string such as “core”, “current-aircraft” or “addons/⟨addonId⟩”

Returns: The FGTranslate instance

If you intend to query translations from one domain only, better pass it directly to the constructor, if possible.

Definition at line 33 of file FGTranslate.cxx.

◆ setupGhost()

void FGTranslate::setupGhost ( )

static

Set up a Nasal type that wraps FGTranslate.

Definition at line 224 of file FGTranslate.cxx.

◆ translationUnit()

std::shared_ptr< TranslationUnit > FGTranslate::translationUnit	(	const std::string &	resource,
		const std::string &	basicId,
		int	index = 0 ) const

Return a shared pointer to a TranslationUnit.

Parameters

resource	same as for get()
basicId	same as for get()
index	same as for get()

This function allows one to efficiently perform several operations on the same translatable string (for instance, querying whether it has plural forms before getting a translation, or retrieving several translations for different values of the “cardinal number”).

Definition at line 51 of file FGTranslate.cxx.

The documentation for this class was generated from the following files:

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ intType

Constructor & Destructor Documentation

◆ FGTranslate()

Member Function Documentation

◆ get()

◆ getAll()

◆ getCount()

◆ getPlural()

◆ getPluralWithDefault()

◆ getResource()

◆ getWithDefault()

◆ setDomain()

◆ setupGhost()

◆ translationUnit()