FGTranslate#
-
class FGTranslate#
Class for retrieving translated strings.
The default 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 parameter (“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
TranslationUnitobject 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");
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");
Public Functions
-
explicit FGTranslate(const std::string &domain = "core")#
Constructor.
The constructed FGTranslate instance will allow retrieving translations from the chosen domain. The domain must already exist when the constructor is called.
- Parameters:
domain – a string such as “core”, “current-aircraft” or “addons/⟨addonId⟩”
-
FGTranslate &setDomain(const std::string &domain)#
Change the domain from which to retrieve translations.
If you intend to query translations from one domain only, better pass it directly to the constructor, if possible.
- Parameters:
domain – a string such as “core”, “current-aircraft” or “addons/⟨addonId⟩”
- Returns:
The FGTranslate instance
-
flightgear::TranslationDomain::ResourceRef getResource(const std::string &resourceName) const#
Get the specified resource.
This function logs warnings if the domain or resource can’t be found.
- Parameters:
resourceName – name of the resource
- Returns:
A shared pointer to the resource
-
std::string get(const std::string &resource, const std::string &basicId, int index = 0) const#
Get a single translation.
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.
- 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
-
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.
- Parameters:
cardinalNumber – an integer corresponding 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
-
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.
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”).
Public Static Functions
-
static void setupGhost()#
Set up a Nasal type that wraps FGTranslate.
-
explicit FGTranslate(const std::string &domain = "core")#