Localization

So far we haven't mentioned why all GUI elements use the HString type for holding string information, instead of the raw String or WString types.

HString is a localizable string, meaning the actual value of the string can be changed by changing the active language. This ensures you can easily create translations for GUI elements.

Localizing strings

When creating a HString it takes an identifier as input, which must be unique.

HString myLocalizedString(L"_myStringId");

You can then assign values to that identifier through a StringTable resource. You create a StringTable by calling StringTable::create().

HStringTable stringTable = StringTable::create();

You can then use the string table to assign actual language strings for your localized string. This is done by calling StringTable::setString().

stringTable->setString(L"_myStringId", Language::EnglishUS, L"Hello!");
stringTable->setString(L"_myStringId", Language::German, L"Hallo!");
stringTable->setString(L"_myStringId", Language::Spanish, L"!Hola!");

Finally, you need to register the string table with StringTableManager by calling StringTableManager::setTable(). StringTableManager is accessible globally through gStringTableManager().

gStringTableManager().setTable(0, stringTable);

Note: Multiple string tables are supported by giving them different identifiers. By default all HStrings will use the 0th string table, so it is suggest to always set that one for most common localizations.

After the string table is set you can call StringTableManager::setActiveLanguage() to change the current language. If the string table has a localization for the specified language, it will be used by any GUI elements referencing the localized string. The default language is English.

Default localization

If you skip the step of creating the string table and assigning it to StringTableManager, the HString will use its identifier as the display string. In cases where you don't need localization you can just use actual display strings in the identifier field (as we have been doing so far).

HString myLocalizedString(L"Hello!");

You can still localize this string. It will use "Hello!" as its value for the default language (English), which is also its identifier and can be used for assigning other values for it in a string table.

Parameters

Localized strings can use parameters as placeholders to insert other data. This is useful when a localized string needs to contain information like numbers or other non-localized information. Use identifiers like "{0}", "{1}", etc. to specify parameters.

HString myLocalizedString(L"Hello my name is {0}, and I am {1} years old.");

Parameters can then be assigned by calling HString::setParameter().

myLocalizedString.setParameter(0, L"John");
myLocalizedString.setParameter(1, L"30");

Note that translations in all languages should share the same number of parameters.