Localization

Localization

The g11n Library

With Enyo 2.1, we introduced a powerful, versatile library for handling globalization and localization, called g11n. While g11n is packaged as part of Enyo (residing under /lib/g11n/ in the standard distribution), most of the library is designed such that it can be used with any JavaScript framework. Our hope is that you'll find g11n useful, whatever your framework of choice may be.

The heart of g11n lies in the base package. In base, you'll find tools for working with locales, as well as specialized code for localizing strings, numbers, durations, dates and times, and time zones. All apps using g11n should include base.

g11n also features several optional packages--address, name, and phone--which may be included in applications as needed. These packages facilitate the parsing and formatting of addresses (of physical locations), people's names, and phone numbers, respectively.

There is also a mini-package called css, which allows you to automatically load locale-specific stylesheets.

Locales in g11n

While a comprehensive survey of the g11n library lies outside the scope of this document, we'd like to provide you with a basic introduction to help you get started.

The way that g11n works should be familiar to developers with previous localization experience. One part of the library handles strings that have been translated into different languages. By using the appropriate API calls, an app can retrieve and display the right string for a given linguistic/geographic/cultural context (i.e., "locale") without having to concern itself with what the current locale happens to be. Furthermore, while someone on your team still has to do the work of translating strings into multiple languages (and placing the translated strings in the right files), for the most part, this process may be kept separate from app code development.

In addition, the library has access to a repository of data on how different locales deal with numbers, names, dates, addresses, and the like. The g11n API provides functions that let apps retrieve and apply the appropriate set of data parsing and formatting rules for a given locale, without needing to know the detailed rules pertaining to any one locale.

With that in mind, it's no surprise that the basic unit of information in g11n is the locale specifier, a string of the form "<language>" (e.g., "en", "fr"), "<language>_<region>" ("en_us", "fr_ca"), or "<language>_<region>_<variant>" ("en_us_funkytown").

Closely related to the locale specifier is the Locale object. A Locale object is created by passing a locale specifier into the enyo.g11n.Locale constructor method (found in locale.js in the base package). This object is essentially a container for the language, region, and variant data from the specifier, with some convenience functions added for parsing the specifier data and for making comparisons with other locales.

If you look in the file g11n.js from the base package, you'll notice that the g11n library actually keeps track of three different locale specifiers--the uiLocale, formatLocale, and phoneLocale:

• The uiLocale is the overarching default locale for displaying the user interface, including strings. (Note: The code for dealing with localized strings is concentrated in the files resources.js and template.js under base.)

  When a Locale object is created, the uiLocale becomes the current locale (i.e., the locale returned by calls to enyo.g11n.currentLocale()) if it is specified in the passed-in params object. The uiLocale also becomes the current locale if it is included in the parameters passed to enyo.g11n.setLocale(params).

• The formatLocale is a locale used for formatting dates and times, durations, numbers, percentages, currency, addresses, and names. Like uiLocale, it may be passed as a parameter to either enyo.g11n.Locale() or enyo.g11n.setLocale(); you may retrieve the current value by calling enyo.g11n.formatLocale(). If no formatLocale is specified, the current locale is used.

• The phoneLocale serves as a "home" locale for parsing and formatting phone numbers that do not contain an explicit country code. To get the current value, call enyo.g11n.phoneLocale(). (Internally, the phone package has its own unique concept of what a phone locale is--see PhoneLoc.js.)

Within the g11n library, localized data exists in JSON-based text files, which are generally named according to language, region, and variant, and stored in a directory called data.

A Rough Guide

The following table summarizes the most significant objects and modules in g11n, grouped by the type of data being localized. It is provided as a source of pointers to additional information in the online Enyo API Viewer.

Data Type	Key Object(s)	Module(s)
Locale	enyo.g11n.Locale, enyo.g11n.Fmts	locale.js, fmts.js
String	enyo.g11n.Resources, $L (function)	resources.js, template.js
Character	enyo.g11n.Char	character.js
Number	enyo.g11n.NumberFmt	numberfmt.js
Date	enyo.g11n.DateFmt	datetime.js
Duration	enyo.g11n.DurationFmt	duration.js
Address	enyo.g11n.Address	address.js, format.js
Name	enyo.g11n.Name, enyo.g11n.NameFmt	name.js, format.js
Phone Number	enyo.g11n.PhoneNumber, enyo.g11n.PhoneFmt	phone.js, format.js

Adding g11n to Your App

The effort needed to add g11n to an app is really quite minimal.

Enyo Apps

To use g11n in an Enyo application, include the library just as you would onyx or layout:

• In your app's lib directory, check out the g11n repo from GitHub. (In a command-line git client, you can do this by issuing the command git clone [email protected]:enyojs/g11n.git.)

• In the app's package.js file, add an entry for "$lib/g11n".

Non-Enyo Apps

To use g11n in a non-Enyo app, do the following:

• In your app's root directory, check out the Enyo core:

    git clone [email protected]:enyojs/enyo.git
  

• Then check out the g11n library:

    git clone [email protected]:enyojs/g11n.git
  

• Finally, in your index.html file, add the following <script> tags:

    <script src="enyo/enyo.js">
    <script src="g11n/package.js">
  

To learn more about g11n, see the documentation in the API Viewer (where individual files from the library are listed under the "Modules" tab), as well as the example code in the Enyo Sampler.