Localization

Table of Contents

• Translation on the fly
• Changing the language dynamically
• Notes

Coherent GT provides a localization facility called via the Coherent::UIGT::LocalizationManager class. Checkout the Sample - Localization sample found in the package to see it in action.

Note

This section refers only to translation of text. If you're interested in input see Input Method Editor (IME) support.

To enable localization you need to implement your version of Coherent::UIGT::LocalizationManager:

// IMPORTANT: This call MUST be thread-safe and callable from any thread
class CustomLocalizationManager : public Coherent::UIGT::LocalizationManager
{
    virtual const char* Translate(const char* text) override
    {
        // 1. Always make sure to return UTF8-encoded text.
        // 2. The string returned MUST outlive the Translate method. It will
        // be immediately copied but still, it needs to survive the stack frame destruction.
        return ConvertToUTF8(TranslateTextAccordingToCurrentLocale(text));
    }
};
...
// Later when initializing your system
CustomLocalizationManager manager; // Make sure this object outlives the system
SystemSettings settings;
settings.LocalizationManagerInstance = &manager;
auto system = InitializeUIGTSystem(license, settings);

Next, in your HTML page add the data-l10n-id attribute to any element you need localized:

<button data-l10n-id="TextForStartGame"></button>

When parsing the HTML, Coherent GT will automatically call CustomLocalizationManager::Translate("TextForStartGame") when creating the button. Creating elements dynamically will also trigger translation, for instance:

var container = document.getElementById("container");
container.innerHTML = '<button data-l10n-id="TextForStartGame"></button>'

Translation on the fly

If you need to translate text dynamically after an element has been created, you can call engine.translate(text) from JavaScript. For example, to get the translated value of the button above, use:

var translatedText = engine.translate('TextForStartGame');

In case you need to need update all localized elements, use the engine.reloadLocalization() method which will do precisely that by calling engine.translate for each element.

Changing the language dynamically

If you need to change the language, it is up to your application to keep track of the current language and update the state of your custom localization manager.

One way of achievieving this behaviour is the following:

class CustomLocalizationManager : public Coherent::UIGT::LocalizationManager
{
    virtual const char* Translate(const char* text) override
    {
        // 1. Always make sure to return UTF8-encoded text.
        // 2. The string returned MUST outlive the Translate method. It will
        // be immediately copied but still, it needs to survive the stack frame destruction.
        return ConvertToUTF8(TranslateTextAccordingToCurrentLocale(text));
    }
    // This method should update the current language / locale
    void ChangeLanguage(const std::string& language);
};
..
// When initializing your view
view->BindCall("ChangeLanguage",
    Coherent::UIGT::MakeHandler(&localizationManager, &CustomLocalizationManager::ChangeLanguage));

Use JavaScript to notify your game that the language has changed:

engine.call("ChangeLanguage", "spanish").then(function () {
    // Use engine.reloadLocalization() to update the translations on all localized elements
    // after the call to ChangeLanguage has completed.
    engine.reloadLocalization();
});

The provided Sample - Localization project provided with the package shows how to do exactly that.

Notes

1. Automatic translation will remove all children from the element as well as any other text and replace them with the value returned from your localization manager.
2. If no localization manager is passed to Coherent::UIGT::SystemSettings, translation will not happen and the data-l10n-id attribute will be ignored.
3. Naturally, translation will not work in your browser. Calling engine.translate(text) there will return the argument with which it was called. Use engine.reloadLocalization() to initialize any the localized elements to the their localization keys.