Text Localization for Web Application

1 Introduction

This article helps you internationalize resources of your applications in Tizen Platform. Language localization is the process of translating a product into different languages and adapting what is said to a specific country or region.

This article particularizes the implementation of a simple L10n algorithm for string localization in Tizen web application. Also it uses content-based localization which allows to localize application without page reloading.

Target environment:

Target SDK: Tizen SDK 2.3.1 (wearable), Tizen SDK 2.4 (mobile)

 


2 Localization models

2.1 Folder-based localization

  • Web App contents can be localized in file unit according to W3C Widget P&C specification
  • The localization requires page reloading, and the localized contents will only be reflected at next launching time
  • Folder-based localization is configurable through Web Localization view on the Tizen IDE.

 

For further information to configure folder-based localization, please refer to the link below.

https://developer.tizen.org/development/tools/web-tools/web-localization

 

2.2 Element-based localization

  • Configuration document can be localized with xml:lang attribute

 

Folling link shows how to configure file localization.

https://www.w3.org/TR/widgets/#element-based-localization

 

2.3 Content-based localization

  • System locale change event can be listened with Tizen System Info API
  • L10n routine needs to be implemented in locale change event handler

 

Content-based localization takes following steps:

  • Create translations. Create separate files for each supported languages that contains the translated strings.
  • Markup the HTML. Add custom attribute to each element in the HTML that need to be translated.
  • Implement l10n algorithm.  Algorithm inserts the correct strings into the HTML depending on locale.
  • Add listener to change the locale. Add event listener to listen changes LOCALE property in System Info API.

 

2.3.1  How to create translation

Create a “locales” folder in package structure if the folder does not exist, and then add ,json files to support each language (f.e. en.json for English, de.json for German language).

locales_directory.png

Figure 1

Each .json file consists of simple keys/values pair of an object.

Where key - unique identifier for the strings and used as value for custom attribute in the HTML.

value - translation of the string in this particular language.

 

en.json

{
    "label_text": "English language",
    "button_text": "Alert Error",
    "error_message": "Internal server error."
}

de.json

{
    "label_text": "Deutsche sprache",
    "button_text": "Alarm Fehler",
    "error_message": "Interner Serverfehler."
}

The other .json files contains the same keys, but the values will be translated with corresponding text for each locale.

 

2.3.2 How to markup the HTML

Add a custom attribute to every element in HTML whose content needs to be translated. The name of the attribute is ”tr” and its value is an identifier to get appropriate text from json file.

 

<p tr="label_text"></p>
<button id="button" tr="button_text"></button>

This identifier is used as a key to look up the correct translation of the string.

Localizable elements should also not have any content or child elements because the localization will overwrite them.

getJson() method of the jQuery is used to get current location in order to load appropriate locale from added .json files.

var localStrings = null;

$.getJSON("/locales/"+currentLanguage+".json", function(json) {
    localStrings = json;
    translateElement($(document))
});

This method load key/value pairs to js object.

 

2.3.3 How to implement l10n algorithm

 

To find nodes in the HTML marked with “tr” attribute and replace their contents with values from appropriate .json file, need to implement simple l10n algorithm.

 L10n algorithm finds all elements which have the “tr” attribute and use the attribute's value as a key to look up the correct translation of the string, given the current device language. After this assign this translation as the element's text.

</**
 * Function for string translation
 */
function tr(str){
    if (typeof(localStrings)!= 'undefined') {
        if(typeof(localStrings[str]) != 'undefined')
            str = localStrings[str];
    }
    return str;
}

/**
 * Function for translating strings in html file
 */
function translateElement(jqElement){    
    function fixElem($this){
        $this.text(tr($this.attr("tr")));
    }
   
    jqElement.find("*[tr]").each(function(){         
        fixElem($(this));
    });
 }

Also tr() function can be used independently in js, f.e. as an argument for alert():

alert(tr("error_message"));

 


2.3.4 How to add listener to get locale change event

 

There may be two ways to change locale in application. Locally – internal application settings or change locale (display language) in device setting.

To listen changes locale in device setting used event listener to LOCALE property in Web SystemInfo API:

var id = null;

function onSuccessCallback(locale) {
   var tmp = locale.language.substring(0,2);
   $.getJSON("/locales/"+tmp+".json", function(json) {
    localStrings = json;
    translateElement($(document))});
}

id = tizen.systeminfo.addPropertyValueChangeListener("LOCALE", onSuccessCallback);

When addPropertyValueChangeListener() method called, it asynchronously starts a watch to system event associated with the selected property. When a system event is successfully received invoke the associated successCallback  with an object containing the property values.

Returns listenerId that can be used to remove listner when app closed:

if( ev.keyName === "back" ) {
   …
            if( pageid === "main" && !activePopup ) {
                try {
                if (id != null) {
                        tizen.systeminfo.removePropertyValueChangeListener(id);
                    }
                    tizen.application.getCurrentApplication().exit();
                } catch (ignore) {
                }
            } else {
                window.history.back();
            }
        }

To listen changes locale in application settings:

Create settings with select element:

<select id="select">
    <option value="de">German</option>
    <option value="en">English</option>
    <option value="fr">French</option>
    <option value="it">Italian</option>
    <option value="ja">Japanese</option>
    <option value="ru">Russian</option>
</select>

 

Add onchange event listener which is called when user change locale:

<script>
var currentLanguage = null;

document.getElementById("select").addEventListener("change", function(){
        currentLanguage = this.value;
        localStorage.setItem("currentLanguage", this.value);
        $.getJSON("/locales/"+currentLanguage+".json", function(json) {
            localStrings = json;
            translateElement($(document))});
});
</script>

Current language installed for application may be stored in web storage or obtained from system using SystemInfo API.

Data stored in localStorage has no expiration date and can be used  to store application settings. Using web storage:

Var currentLanguage = null,
    defaultLenguage = "en";

if(!localStorage.getItem("currentLanguage"))
        currentLanguage = defaultLanguage;
else
        currentLanguage = localStorage.getItem("currentLanguage");

To get current language from system settings used getPropertyValue() method with LOCALE property. This method in successCallback returns current language set in Language device settings.

var currentLanguage = null,
    defaultLenguage = "en",
    supportedLanguages = ["en", "fr", "ru", "de", "it", "ja"];

tizen.systeminfo.getPropertyValue("LOCALE", function(locale) {
        var tmp = locale.language.substring(0,2);
        if(supportedLanguage.indexOf(tmp) > -1) {
               currentLanguage = tmp;
        } else {
               currentLanguage = defaultLanguage;
        }
});

locale.language indicates the current language setting in the (LANGUAGE)_(REGION) syntax.

If current language from device settings is not included in supported languages then loaded default languages otherwise loaded the corresponding file with locale.

 

3 Conclusion

Based on this article can be developed a simple L10n algorithm to localize web application without page reloading.  As localization algorithm can be used any third-party implementation of L10n.

References

 

https://developer.tizen.org/development/guides/web-application/tizen-fea...

 

https://developer.tizen.org/development/tools/web-tools/web-localization

 

https://www.w3.org/TR/widgets/

 

List
SDK Version Since: 
2.3.1