Text Translation

// IMPORTANT: This call MUST be thread-safe and callable from any thread
class CustomLocalizationManager : public cohtml::ILocalizationManager
{
    virtual const char* Translate(const char* text) override
    {
        // 1. Always make sure to return UTF-8 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 the system
auto library = cohtml::Library::Initialize(HUMMINGBIRD_LICENSE_KEY, params);
CustomLocalizationManager manager; // Make sure this object outlives the system
cohtml::SystemSettings settings;
settings.LocalizationManagerInstance = &manager;
auto system = library->CreateSystem(settings);

Localize HTML content by adding data-l10n-id attribute to any element:

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

Nothing else needed further to translate text - cohtml::ILocalizationManager::Translate("TextStartGameBtn") is called automatically during button creation. Creating elements dynamically also triggers translation:

var container = document.getElementById("container");

container.innerHTML = '<button data-l10n-id="TextForStartGame"></button>'

Translation on The Fly

Another useful feature is the possibility to get the translated value of a key from JavaScript for example in order to create dynamically text element.

var info = document.getElementById("ProfileInfo");
var translatedLabel = engine.translate("ContactNumber");
info.appendChild(document.createTextNode(translatedLabel + contactNumber));

To update all the localized elements after changing the locale, for example, call the engine.reloadLocalization() method which acts by calling engine.translate on each element in the DOM tree.

Changing the Locale Dynamically

Hummingbird must be notified whenever the application changes its locale in order to apply the new localization rules - the library keeps no track of the current locale and will not detect the need to reload the localized elements content. Therefore you need to manually call engine.reloadLocalization. Example:

class CustomLocalizationManager : public cohtml::ILocalizationManager
{
    virtual const char* Translate(const char* text) override;
    void ChangeLanguage(const char*);
    void OnReadyForBindings(View* view)
    {
        std::function<void(const std::string&)> handler = [this](const std::string& language)
        {
            this->ChangeLanguage(language.c_str());
        };
        view->BindCall("ChangeLanguage", cohtml::MakeHandler(handler));
    }
};

Use JavaScript to notify the UI that the language has changed:

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

Notes

Text translation removes all children from the element including all other text and replace them with the value returned from the localization manager. However if text translation for the specified key is not found whatever is present in the element is not touched, which allows for default text values addition to make debugging easier upon forgotten translation.
If no localization manager is provided, the data-l10n-id attribute will be ignored.
Translation will not work in the browser. Calling engine.translate(text) there will return the argument which it was called with. Use engine.reloadLocalization() to initialize any the localized elements to the their localization keys.

Table of Contents

Text Translation

Translation on The Fly

Changing the Locale Dynamically

Notes