Skip to content

Localization

Jump to bottom
Roy Sutton edited this page May 23, 2014 · 12 revisions

Localization

The iLib Library

Please refer to the documentation here for using iLib with Enyo: http://enyojs.com/docs/2.4.0/building-apps/localization.html

The g11n Library

The g11n Library has been deprecated with Enyo 2.4. The remainder of this document is preserved for historical purposes.

With Enyo 2.1, we introduced a powerful, versatile library for handling globalization and localization, called g11n. While we are distributing g11n as part of the Enyo project--as an optional library that fits neatly into the standard distribution under /lib/g11n/--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--name, phone, and address--which may be included in applications as needed. These packages facilitate the parsing and formatting of personal names, phone numbers, and addresses (of physical locations), respectively. (Note: For the initial release of g11n, the address package has "work-in-progress" status.)

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 for details.)

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)
Locales enyo.g11n.Locale, enyo.g11n.Fmts locale.js, fmts.js
Strings enyo.g11n.Resources, $L (function) resources.js, template.js
Characters enyo.g11n.Char, enyo.g11n.Fmts character.js, fmts.js
Dates enyo.g11n.DateFmt, enyo.g11n.Fmts datetime.js, fmts.js
Numbers enyo.g11n.NumberFmt numberfmt.js
Durations enyo.g11n.DurationFmt duration.js
Names enyo.g11n.Name, enyo.g11n.NameFmt name.js, format.js
Phone Numbers enyo.g11n.PhoneNumber, enyo.g11n.PhoneFmt phone.js, format.js
Addresses (work-in-progress) enyo.g11n.Address, enyo.g11n.AddressFmt address.js, format.js

Current Support

Dates and Numbers

The g11n library currently supports date and number formatting for the following countries:

Albania, Argentina, Australia, Austria, Bahrain, Belgium, Bolivia, Brazil, Bulgaria, Canada, Chile, China, Colombia, Costa Rica, Croatia, Czech Republic, Democratic Republic of the Congo, Denmark, Dominican Republic, Ecuador, Egypt, El Salvador, Estonia, Finland, France, Germany, Great Britain, Greece, Guatamala, Honduras, Hong Kong, Hungary, Iceland, India, Indonesia, Ireland, Israel, Italy, Jamaica, Japan, Jordan, Kazahkstan, Kenya, Latvia, Lesotho, Libya, Lithuania, Luxembourg, Macedonia (The Former Yugoslav Republic of), Malaysia, Malta, Mexico, Montenegro, Morocco, Mozambique, Netherlands, New Zealand, Nicaragua, Norway, Pakistan, Panama, Paraguay, Peru, Philippines, Poland, Portugal, Puerto Rico, Republic of Korea, Republic of Serbia, Romania, Russian Federation, Saudi Arabia, Singapore, Slovakia, South Africa, Spain, Sweden, Switzerland, Taiwan, Thailand, Turkey, Ukraine, United Arab Emirates, United Republic of Tanzania, United States of America, Uruguay, Venezuela

Names

g11n currently supports the parsing and formatting of personal names in the following languages:

Chinese, Dutch, English, French, German, Italian, Spanish

Phone Numbers (Formatting)

g11n currently supports phone number parsing and formatting for the following countries:

Australia, Belgium, China, France, Germany, Hong Kong, India, Ireland, Italy, Luxembourg, Mexico, Netherlands, New Zealand, Singapore, Spain, United Kingdom, United States of America

Phone Numbers (Geographical Location)

g11n currently supports the ability to determine a phone number's region of origin within a country for the following countries:

Australia, Belgium, China, France, Germany, India, Ireland, Italy, Mexico, Netherlands, New Zealand, Spain, United Kingdom, United States of America

Addresses

While the g11n library's support for parsing and formatting addresses is currently a work-in-progress, we plan to have support for addresses in the following countries:

Australia, Belgium, Canada, China, France, Germany, Hong Kong, India, Ireland, Italy, Luxembourg, Mexico, Netherlands, New Zealand, Singapore, Taiwan, United Kingdom, United States of America

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 git@github.com: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 git@github.com:enyojs/enyo.git

  • Then check out the g11n library:

      git clone git@github.com: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.

Clone this wiki locally