The jQuery Globalization plugin uses the language tags
defined in the RFC 4646 and RFC 5646 standards to identity cultures (see http://tools.ietf.org/html/rfc5646).
A language tag is composed out of one or more subtags separated by hyphens. For
example:
Language Tag
|
Language Name (in English)
|
en-AU
|
English (Australia)
|
en-BZ
|
English (Belize)
|
en-CA
|
English (Canada)
|
Id
|
Indonesian
|
zh-CHS
|
Chinese (Simplified) Legacy
|
Zu
|
isiZulu
|
Notice that a single language, such as English, can have
several language tags. Speakers of English in Canada format numbers,
currencies, and dates using different conventions than speakers of English in
Australia or the United States. You can find the language tag for a
particular culture by using the Language Subtag Lookup tool located here:
http://rishida.net/utils/subtags/
The jQuery Globalization plugin download includes a folder
named globinfo that contains the information for each of the 350 cultures.
Actually, this folder contains more than 700 files because the folder includes
both minified and un-minified versions of each file.
For example, the globinfo folder includes JavaScript files
named jQuery.glob.en-AU.js for English Australia, jQuery.glob.id.js for
Indonesia, and jQuery.glob.zh-CHS for Chinese (Simplified) Legacy.
Example 1: Setting a Particular Culture
Imagine that you have been asked to create a German website
and want to format all of the dates, currencies, and numbers using German
formatting conventions correctly in JavaScript on the client. The HTML for the
page might look like this:
Notice the span tags above. They mark the areas of the page
that we want to format with the Globalization plugin. We want to format the
product price, the date the product is available, and the units of the product
in stock.
To use the jQuery Globalization plugin, we’ll add three
JavaScript files to the page: the jQuery library, the jQuery Globalization
plugin, and the culture information for a particular language:
In this case, I’ve statically added the jQuery.glob.de-DE.js
JavaScript file that contains the culture information for German. The language
tag “de-DE” is used for German as spoken in Germany.
Now that I have all of the necessary scripts, I can use the
Globalization plugin to format the product price, date available, and units in
stock values using the following client-side JavaScript:
The jQuery Globalization plugin extends the jQuery library
with new methods - including new methods named preferCulture() and format().
The preferCulture() method enables you to set the default culture used by the
jQuery Globalization plugin methods. Notice that the preferCulture() method
accepts a language tag. The method will find the closest culture that matches
the language tag.
The $.format() method is used to actually format the
currencies, dates, and numbers. The second parameter passed to the $.format()
method is a format specifier. For example, passing “c” causes the value to be
formatted as a currency. The ReadMe file at github details the meaning of all
of the various format specifiers: http://github.com/nje/jquery-glob
When we open the page in a browser, everything is formatted
correctly according to German language conventions. A euro symbol is used for
the currency symbol. The date is formatted using German day and month names.
Finally, a period instead of a comma is used a number separator:
You can see a running example of the above approach with the
3_GermanSite.htm file in this samples download.
Example 2: Enabling a User to Dynamically Select a
Culture
In the previous example we explicitly said that we wanted to
globalize in German (by referencing the jQuery.glob.de-DE.js file). Let’s now
look at the first of a few examples that demonstrate how to dynamically set the
globalization culture to use.
Imagine that you want to display a dropdown list of all of
the 350 cultures in a page. When someone selects a culture from the dropdown
list, you want all of the dates in the page to be formatted using the selected
culture.
Here’s the HTML for the page:
Notice that all of the dates are contained in a <span>
tag with a data-date attribute (data-* attributes are a new feature of HTML 5
that conveniently also still work with older browsers). We’ll format the date
represented by the data-date attribute when a user selects a culture from the
dropdown list.
In order to display dates for any possible culture, we’ll
include the jQuery.glob.all.js file like this:
The jQuery Globalization plugin includes a JavaScript file
named jQuery.glob.all.js. This file contains globalization information for all
of the more than 350 cultures supported by the Globalization plugin. At
367KB minified, this file is not small. Because of the size of this file,
unless you really need to use all of these cultures at the same time, we
recommend that you add the individual JavaScript files for particular cultures
that you intend to support instead of the combined jQuery.glob.all.js to a
page. In the next sample I’ll show how to dynamically load just the language
files you need.
Next, we’ll populate the dropdown list with all of the
available cultures. We can use the $.cultures property to get all of the loaded
cultures:
Finally, we’ll write jQuery code that grabs every span
element with a data-date attribute and format the date:
The jQuery Globalization plugin’s parseDate() method is used
to convert a string representation of a date into a JavaScript date. The
plugin’s format() method is used to format the date. The “D” format specifier
causes the date to be formatted using the long date format.
And now the content will be globalized correctly regardless
of which of the 350 languages a user visiting the page selects. You can
see a running example of the above approach with the 4_SelectCulture.htm file
in this samples download.
Example 3: Loading Globalization Files Dynamically
As mentioned in the previous section, you should avoid
adding the jQuery.glob.all.js file to a page whenever possible because the file
is so large. A better alternative is to load the globalization information that
you need dynamically.
For example, imagine that you have created a dropdown list
that displays a list of languages:
The following jQuery code executes whenever a user selects a
new language from the dropdown list. The code checks whether the globalization
file associated with the selected language has already been loaded. If the
globalization file has not been loaded then the globalization file is loaded
dynamically by taking advantage of the jQuery $.getScript() method.
The globalizePage() method is called after the requested
globalization file has been loaded, and contains the client-side code to
perform the globalization.
The advantage of this approach is that it enables you to
avoid loading the entire jQuery.glob.all.js file. Instead you only need to load
the files that you need and you don’t need to load the files more than once.
The 5_Dynamic.htm file in this samples download demonstrates how to implement this
approach.
Example 4: Setting the User Preferred Language
Automatically
Many websites detect a user’s preferred language from their
browser settings and automatically use it when globalizing content. A user can
set a preferred language for their browser. Then, whenever the user requests a
page, this language preference is included in the request in the
Accept-Language header.
When using Microsoft Internet Explorer, you can set your
preferred language by following these steps:
Select the menu option Tools, Internet Options.
Select the General tab.
Click the Languages button in the Appearance section.
Click the Add button to add a new language to the list of
languages.
Move your preferred language to the top of the list.
Notice that you can list multiple languages in the Language
Preference dialog. All of these languages are sent in the order that you listed
them in the Accept-Language header:
Accept-Language: fr-FR,id-ID;q=0.7,en-US;q=0.3
Strangely, you cannot retrieve the value of the
Accept-Language header from client JavaScript. Microsoft Internet Explorer and
Mozilla Firefox support a bevy of language related properties exposed by the
window.navigator object, such as windows.navigator.browserLanguage and
window.navigator.language, but these properties represent either the language
set for the operating system or the language edition of the browser. These
properties don’t enable you to retrieve the language that the user set as his
or her preferred language.
The only reliable way to get a user’s preferred language
(the value of the Accept-Language header) is to write server code. For example,
the following ASP.NET page takes advantage of the server Request.UserLanguages
property to assign the user’s preferred language to a client JavaScript
variable named acceptLanguage (which then allows you to access the value using
client-side JavaScript):
In order for this code to work, the culture information
associated with the value of acceptLanguage must be included in the page. For
example, if someone’s preferred culture is fr-FR (French in France) then you
need to include either the jQuery.glob.fr-FR.js or the jQuery.glob.all.js
JavaScript file in the page or the culture information won’t be
available. The “6_AcceptLanguages.aspx” sample in this samples download demonstrates how to implement this
approach.
If the culture information for the user’s preferred language
is not included in the page then the $.preferCulture() method will fall back to
using the neutral culture (for example, using jQuery.glob.fr.js instead of
jQuery.glob.fr-FR.js). If the neutral culture information is not available then
the $.preferCulture() method falls back to the default culture (English).
Example 5: Using the Globalization Plugin with the
jQuery UI DatePicker
One of the goals of the Globalization plugin is to make it
easier to build jQuery widgets that can be used with different cultures.
We wanted to make sure that the jQuery Globalization plugin
could work with existing jQuery UI plugins such as the DatePicker plugin. To
that end, we created a patched version of the DatePicker plugin that can take
advantage of the Globalization plugin when rendering a calendar. The following
image illustrates what happens when you add the jQuery Globalization and the
patched jQuery UI DatePicker plugin to a page and select Indonesian as the
preferred culture:
Notice that the headers for the days of the week are
displayed using Indonesian day name abbreviations. Furthermore, the month names
are displayed in Indonesian.
You can download the patched version of the jQuery UI
DatePicker from our github website. Or you can use the version included in this
samples download and used by the 7_DatePicker.htm sample
file.