Translating the app into the user's language

This is called internationalization (or i18n, the fact of making the app's string translatable) and localization (l10n, the fact of translating the internationalized, or i18n'd, strings).

Depending of the complexity of your app, there are two ways of turning your monolingual app into a multilingual one.

Using Netvibes's default strings

All of Netvibes' official apps (that is, the ones you can find directly in Netvibes "Add Content, Essential Widgets") are i18n'd.

These translations are made by volunteers, through the Translate tool. Once a string is translated, this translation can apply to your app if you use the exact same original English string.

This method is not the best, since you can't use custom messages, but it's the easiest to set up, as long as you can live with the available strings.

Such strings are 'Yes', 'No', 'Monday' and other weekdays, 'January' and other months, 'Username', 'Password', 'Search', 'Results', 'Loading...', 'About', ...

Their use is pretty simple: you just need to enclose the string within the UWA.i18n JavaScript method, and the translation will automatically apply according to the user's language setting.

Example:

widget.setBody(UWA.i18n('Loading...'));

Using your own custom strings

Once you have custom strings to translate, you need to set up your own translations files, and call it using an Ajax method.

But you'd have to know the user's language to properly set the translation.

UWA provides it with two dedicated widget properties: <UWA.Widget.locale> and <UWA.Widget.lang>, they should be used to retrieve the user's country (locale), and their language/dialect (lang).

Example of widget.lang and widget.locale usage:

var lang = widget.lang,
    locale = widget.locale;

widget.setBody(UWA.String.format(UWA.i18n('Hello, my language is "{0}" and my country "{1}".', lang, locale));

In standalone mode, widget.locale and widget.lang is set to browser values.

As soon as the app is previewed or included within Netvibes or any other supported environment, widget.locale would change the user's country ISO code, and widget.lang to a combination of the user's language, and the regional dialect.

Therefore, for English you have 'en' and 'en_US', 'en_UK', but also 'en_PH' (Philippines). Spanish has many, with 'es', 'es_ES' (Spain), 'es_AR' (Argentina), 'es_CL' (Chile), 'es_CO' (Colombia), 'es_MX' (Mexico) and 'es_VE' (Venezuela). French also has a wide range of dialects: 'fr', 'fr_FR', 'fr_BE', 'fr_CH', 'fr_QC', etc.

Once you have the proper lang and locale, there is no one true way of retrieving the needed strings - it's really up to you to set up the code that will handle localization.

The main point is to retrieve the translated strings using an Ajax request that features the widget.locale or widget.lang value and call UWA.i18n with an Object argument populate with message/translation pair values.

Here's how you could set it up on the client side.

var MyWidget = {

    onLoad: function () {

        // Set App state to loading with a message
        widget.setBody(UWA.i18n('Loading...'));

        // Load translation from JSON Object and update UWA.i18n translations
        UWA.Data.getJson(
            'http://api.example.org/i18n?lang=' + widget.lang,
            function (messages) {

                // Update UWA.i18n with new translations
                UWA.i18n(messages);

                // Launch your app here once translation are loaded
                MyWidget.onReady();
            }
        );
    },

    onReady: function() {

        // Alias
        var i18n = UWA.i18n;

        widget.setTitle(i18n('My App'));
        widget.setBody(UWA.String.format(i18n('Hello {0} welcome on {1}.', 'Bob', i18n('My App')));
    }
};

// widget.onLoad() is fired when the app is fully loaded
// or when the preferences are validated
widget.addEvent('onLoad', MyWidget.onLoad);

Here's the example response of server for lang with value "fr".

{
    "My App": "Mon Application",
    "Hello {0} welcome on {1}.": "Bonjour {0} bienvenue sur {1}."
}