´óÏó´«Ã½

Overview

Internationalisation (or i18n for short) is the process of making a piece of software such that it can be localised. Localisation is the process of actually customising the software to be correct for particular locale.

A locale is a concept that refers to a specific, usually regional, community of people who share similar cultural and linguistic conventions. A locale includes things such as the spoken language but it also defines rules for displaying written text, units such as the date and time, currency symbols, and the decimal separator. A locale is identified by a locale tag, such as "en-GB", "fr-CA" or "de-DE".

The glow.i18n module internationalises Glow by providing the framework for setting the locale of any of Glow's modules or widgets, and it helps users internationalise their own code.

Using Locale Tags in Glow

A locale tag is a string that identifies a locale. Tags can be more or less specific, depending on how many subtags they contain. For example the tag "en" identifies the locale of all English language speakers, whilst "en-AU" means English language speakers in the region of Austalia. Notice that subtags are separated by a dash and should appear in the correct order and with the correct letter case. Glow supports the following syntax of subtags, a subset of the IANA specified tag structure:

language-script-region-variant

These four types of subtags are defined as the following:

• language - 2 or 3 lowercase letters, representing the spoken language. eg 'en' for English.
• script - An uppercase letter followed by 3 lowercase letters, representing the script in which the language is written. eg 'Latn' for the Latin script in which English is normally written.
• region - 2 upper case letters or a 3 digit number, representing the geographical region covered by this locale. eg 'GB' for Great Britain.
• variant - 4 or more characters, a mixture of lower case letters or numbers. Represents a cultural variation of the locale.

At a minimum a locale tag in Glow must have at least a language subtag. Optionally it can also have as many of the other three subtags as may be required. For example, all of the following are valid locale tags in Glow:

• en - language generic: English
• en-GB - language-region: British English
• en-Runr - language-script: English written in Runic script
• en-Runr-GB - language-script-region: English written in Runic script as used in Great Britain
• en-GB-scouse - language-region-variant: Scouse variant of British English

Note that while Glow does not directly support the complete IANA specification for locale tags, neither does it enforce compliance with the IANA registry of subtags, or strictly require only the subtag formats above.

When parsing a given locale tag, Glow will look for each subtag according to the expected order and format. If a subtag is unrecognised, encountered out of order, or if it represents something that has already been seen, it will be ignored. For example consider the local tag 'GB-cy-9-en-US'. It will be parsed as 'cy-US': 'GB' is out of order; 'en' is a redundant language subtag, after 'cy'; and '9' is not a recognised subtag at all.

When parsing a locale tag, Glow will return the locale data for the closest match it can find. For example if you request a locale module for the locale 'en-GB-cockney' you would get data for 'en-GB' if no locale for the cockney variant was available. As a last resort, if no subtags in your request are found to match, Glow will assume the default locale tag which is simply 'en'.

What's in a Locale Module?

The data returned by glow.i18n is in the form of locale module. Locale modules are defined by the currently set locale tag and the name of the Glow code module they apply to. For example, to get the locale module that corresponds to the glow.forms module in the 'en-US' locale (assuming it existed) you would use this pattern:

glow.i18n.setLocale('en-US');
var myLocaleModule = glow.i18n.getLocaleModule('GLOW_FORMS');

There is no restriction on what type of data can be stored in a locale module. The vast majority will, of course, be translations of text strings, but information like text direction, date formats, and cultural standards such as how to validate a name could all be included.

Using It

The simplest use case of glow.i18n is to build a web page in a single locale. If that locale is the default for Glow, en, then you don't need to do anything. If it's any other locale, then simply include the locale pack for that locale and then tell Glow to use it. This must be done before any Glow modules are itialised.

Locale modules are grouped together into locale packs. A pack holds all the locale modules related a specific locale. For example, if you had a locale pack for the Welsh language you could include it in your page after the glow.i18n module was loaded.

Then, before you create any Glow objects, set the locale.

glow.i18n.setLocale('cy');

Each time a locale is set Glow keeps track and you can later 'rewind' to a previous locale by using glow.i18n.revertLocale(). This is especially useful if you want a Widget to always appear in a given locale, no matter what the user has selected as the default locale for the rest of the page.

glow.i18n.setLocale('cy');
// your new widget, always in Welsh
glow.i18n.revertLocale(); // now back to whatever it was before

Using glow.i18n to Internationalise Your Own Code

This is best explained as a strategy.

• Use glow.i18n.addLocaleModule to add a locale module for each locale you will be supporting. This should only be done once, eg in the root level of your script rather than per instance of any objects you are creating.
• Set the current locale using setLocale.
• Use glow.i18n.getLocaleModule to access the locale module in the current locale. Make sure that this is done per instance so that if the locale changes, this change is picked up.
• A useful trick here (and one that Glow uses internally) is to populate the locale module with templates that are suitable for glow.lang.interpolate or the interpolate option of glow.dom.create.
• Make sure you only ever get translations or other locale specific data from the module.

As an example we will create a locale modules for an imaginary piece of code named meerkat.widget, with locale data for 'en' and 'fr':

glow.i18n
    .addLocaleModule('MEERKAT_WIDGET', 'en', {
        GREETING : "Hello Meerkats!",
        STATEMENT : "I like meerkats."
    })
    .addLocaleModule('MEERKAT_WIDGET', 'fr', {
        GREETING : "Bonjour Meerkats!",
        STATEMENT : "J'aime les meerkats."
    });

function MeerkatWidget() {
    var myLocale = glow.i18n.getLocaleModule('MEERKAT_WIDGET');

    this.nodes = glow.dom.create("<h1>{GREETING}</h1><p>{STATEMENT}</p>", {interpolate: myLocale});
}

glow.i18n.setLocale('fr');

var meerkat = new MeerkatWidget();

// meerkat.nodes is a glow.dom.Nodelist whose HTML is
// <h1>Bonjour Meerkats!</h1><p>J'aime les meerkats.</p>

Creating Your Own Locale Pack

If Glow does not have a locale pack for the locale you are interested in, you can create your own from scratch, but, to be compatible with Glow, you must include locale data for each of Glow's existing code modules. Once you have created your application in English (using the default 'en' locale), use glow.i18n.checkLocale to tell you what locale modules are in use and then use glow.i18n.addLocaleModule as shown above.

A Note About RTL (Right-To-Left) Language Support

At present Glow does not directly support RTL text (although this is planned). However, Glow modules and widgets all offer you the ability to customise their output, and this may be used to make any changes required to enable RTL in your code.