TranslationResource

class TranslationResource

Class that holds translation units within a resource (“context”)

This class provides functions for adding TranslationUnit instances to a translation “resource”, modifying these objects and retrieving information from them, in particular obtaining translations associated to a translation “basic id” within the resource.

Public Functions

explicit TranslationResource(std::string name) noexcept

Constructor.

Parameters:

name – resource name (used for error messages)

void addTranslationUnit(std::string name, int index, std::string sourceText, bool hasPlural = false)

Add a translation unit to the TranslationResource.

The added TranslationUnit instance has an empty list of target texts.

Parameters:

• name – “basic id” of the translation unit (which corresponds to the element name in the default translation XML file)

• index – zero-based index used to distinguish between elements with the same name within a translation resource

• sourceText – text that the translation unit gives a translation of

• hasPlural – tells whether the translation unit has plural forms (variants chosen based on a “cardinal number”)

void setFirstTargetText(std::string name, int index, std::string targetText)

Set the first target text of a translation unit.

Parameters:

• name – “basic id” of the translation unit to modify

• index – index used to distinguish between translation units that share the same “basic id” (which corresponds to elements having the same name in a default translation XML file)

• targetText – first plural form of the translation associated to name and index (this is the only form for translatable strings that have “no plural form”)

void setTargetTexts(std::string name, int index, std::vector<std::string> targetTexts)

Set all target texts of a translation unit.

Parameters:

• name – same as in setFirstTargetText()

• index – same as in setFirstTargetText()

• targetTexts – vector of strings which are translations in the order of plural forms for the target language of the translation unit

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

Return a shared pointer to a TranslationUnit.

Parameters:

• name – element name (aka “basic id”) in the default translation XML file

• index – zero-based index used to distinguish between elements with the same name in the TranslationResource

Returns:

a shared pointer to the TranslationUnit with this name and index

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

Get a single translation.

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

If there is no translatable string with the specified basicId and index in the TranslationResource, return an empty string.

Parameters:

• 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 &basicId, int index = 0) const

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

Parameters:

• cardinalNumber – an integer corresponding to a number of “things” (concrete or abstract)

• basicId – same as for get()

• index – same as for get()

Returns:

The translated string

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

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

Parameters:

• 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

std::string getPluralWithDefault(intType cardinalNumber, 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)

• 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 &name) const

Get translations for all strings with a given element name.

Parameters:

name – element name (aka “basic id”) in the default translation XML file

Returns:

A vector containing the first target text (i.e., first plural form) of each translated string with the specified element name

std::size_t getCount(const std::string &name) const

Get the number of translated strings with the given element name.

Parameters:

name – element name (aka “basic id”) in the default translation XML file

Returns:

The number of translation units with basic id name in the TranslationResource

Public Static Functions

static void setupGhost()

Set up a Nasal type that wraps TranslationResource.