jQuery Globalization Plugin from Microsoft

Last month I blogged about how Microsoft is starting to make code contributions to jQuery, and about some of the first code contributions we were working on: jQuery Templates and Data Linking support.

Today, we released a prototype of a new jQuery Globalization Plugin that enables you to add globalization support to your JavaScript applications. This plugin includes globalization information for over 350 cultures ranging from Scottish Gaelic, Frisian, Hungarian, Japanese, to Canadian English.  We will be releasing this plugin to the community as open-source.

You can download our prototype for the jQuery Globalization plugin from our Github repository:

http://github.com/nje/jquery-glob

You can also download a set of samples that demonstrate some simple use-cases with it here.

Understanding Globalization

The jQuery Globalization plugin enables you to easily parse and format numbers, currencies, and dates for different cultures in JavaScript. For example, you can use the Globalization plugin to display the proper currency symbol for a culture:

image

You also can use the Globalization plugin to format dates so that the day and month appear in the right order and the day and month names are correctly translated:

image

Notice above how the Arabic year is displayed as 1431. This is because the year has been converted to use the Arabic calendar.

Some cultural differences, such as different currency or different month names, are obvious. Other cultural differences are surprising and subtle. For example, in some cultures, the grouping of numbers is done unevenly. In the "te-IN" culture (Telugu in India), groups have 3 digits and then 2 digits. The number 1000000 (one million) is written as "10,00,000". Some cultures do not group numbers at all. All of these subtle cultural differences are handled by the jQuery Globalization plugin automatically.

Getting dates right can be especially tricky. Different cultures have different calendars such as the Gregorian and UmAlQura calendars. A single culture can even have multiple calendars. For example, the Japanese culture uses both the Gregorian calendar and a Japanese calendar that has eras named after Japanese emperors. The Globalization Plugin includes methods for converting dates between all of these different calendars.

Using Language Tags

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: 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:

image

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:

image

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:

image

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:

image

You can see a running example of the above approach with the 3_GermanSite.htm file in this samples download.

Example: 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.

image

Here’s the HTML for the page:

image

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:

image

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:

image

Finally, we’ll write jQuery code that grabs every span element with a data-date attribute and format the date:

image

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: 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:

image

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.

image

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: 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:

  1. Select the menu option Tools, Internet Options.
  2. Select the General tab.
  3. Click the Languages button in the Appearance section.
  4. Click the Add button to add a new language to the list of languages.
  5. Move your preferred language to the top of the list.

image

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):

image

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: 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:

image

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.

Summary

I’m excited about our continuing participation in the jQuery community. This Globalization plugin is the third jQuery plugin that we’ve released.

We’ve really appreciated all of the great feedback and design suggestions on the jQuery templating and data-linking prototypes that we released earlier this year.  We also want to thank the jQuery and jQuery UI teams for working with us to create these plugins.

Hope this helps,

Scott

P.S. In addition to blogging, I am also now using Twitter for quick updates and to share links. You can follow me at: twitter.com/scottgu

Published Thursday, June 10, 2010 10:34 PM by ScottGu

Comments

# re: jQuery Globalization Plugin from Microsoft

Friday, June 11, 2010 2:22 AM by mjoksa

Very nice. Just keep developing nice plugins like this one and everybody will be excited

# re: jQuery Globalization Plugin from Microsoft

Friday, June 11, 2010 2:38 AM by zire

Three times hooray for contribution :))

# re: jQuery Globalization Plugin from Microsoft

Friday, June 11, 2010 2:45 AM by RoBYCoNTe

Wonderfull! I think very interesting and useful in my new web-apps!

Good Article!

# re: jQuery Globalization Plugin from Microsoft

Friday, June 11, 2010 3:07 AM by Gregor Suttie

That was the problem I had with the MVC issue where I thought the data validation in MVC was playing up, turned out I had to use the EN-GB version of the JQuery script as above.

# re: jQuery Globalization Plugin from Microsoft

Friday, June 11, 2010 3:17 AM by Thor Larholm

Great stuff, as always.

It would be nice if the globalization plugin itself could include the necessary culture information script, if it had not already been included.

# re: jQuery Globalization Plugin from Microsoft

Friday, June 11, 2010 3:21 AM by Juri

Very nice. This will definitely save me some time on our next project. Globalization/Localization is a major point in our ASP.net applications and there was a lack in the availability of appropriate libs on the client-side.

I like MS strategy to invest more in jQuery. Really good move.

# re: jQuery Globalization Plugin from Microsoft

Friday, June 11, 2010 3:25 AM by rickj1

This is going to change the way globalization is done making it a snap it's good to see how you are taking on the big jobs to simplify the developers life thanks for the great work

# re: jQuery Globalization Plugin from Microsoft

Friday, June 11, 2010 3:37 AM by Dave Nicoll

jquery.glob.js ? Hmm, wouldn't that be better as jquery.globalization.js ? .glob doesn't feel right. And jquery.globalization.de-DE.js...?

# re: jQuery Globalization Plugin from Microsoft

Friday, June 11, 2010 3:49 AM by webbes

Great!

# re: jQuery Globalization Plugin from Microsoft

Friday, June 11, 2010 4:02 AM by Esben

This is a great plugin! Thanks!

# re: jQuery Globalization Plugin from Microsoft

Friday, June 11, 2010 4:09 AM by Rail

It's Great!!

But i found few misstakes in formating (my native) Tatar language.

Scott, How we can fix these error?

# re: jQuery Globalization Plugin from Microsoft

Friday, June 11, 2010 4:23 AM by Dan Meineck

Being a stickler here...

Wouldn't 'English' be '£1345.00' and 'Wednesday, 9th June 2010'.

What your example shows is US English :)

Otherwise I think it's absolutely brilliant that you guys are contributing to the jQuery project.

# re: jQuery Globalization Plugin from Microsoft

Friday, June 11, 2010 4:57 AM by Ben

Out of interest does anyone know what the 'EN' refers to in the doctype:

-//W3C//DTD XHTML 1.0 Strict//EN

# re: jQuery Globalization Plugin from Microsoft

Friday, June 11, 2010 5:22 AM by Gordon Bergling

Scott, that are excellent news. :)

# re: jQuery Globalization Plugin from Microsoft

Friday, June 11, 2010 5:32 AM by KierenH

IMO, there's never been a good library for performing basic string manipulation (e.g. formatting) in JavaScript. Awesome!

# re: jQuery Globalization Plugin from Microsoft

Friday, June 11, 2010 6:06 AM by carlhoerberg

I really love Microsoft new approach to open source and the shift to jQuery.

This globalization plugin look all well but ain't currency translation pretty useless? I mean, $100 ain't the same as 100 €. Your still need a external resource to get the actual currency exchange rates.

# re: jQuery Globalization Plugin from Microsoft

Friday, June 11, 2010 6:09 AM by Webdiyer

Great, Thank you, Microsoft!

# re: jQuery Globalization Plugin from Microsoft

Friday, June 11, 2010 6:20 AM by tobi

I think you have an injection vulnerability when you render the first user language.

# re: jQuery Globalization Plugin from Microsoft

Friday, June 11, 2010 9:03 AM by Dennis Persson

A great contribution if we're to adopt jquery in public government webs on a larger scale.

# re: jQuery Globalization Plugin from Microsoft

Friday, June 11, 2010 9:25 AM by Damian@ Protein Shakes For Weight Loss

Thanks for the post. I really like the fact that you used big pictures. Also, too many small fonts on the net these days. It's like everyone has 20/20.

# re: jQuery Globalization Plugin from Microsoft

Friday, June 11, 2010 9:48 AM by Aidan McQuay

Cool, this is the type of thing MS should be focusing on adding to jquery.  They have the specific knowledge from their enterprise experience to do this right the first time.

# re: jQuery Globalization Plugin from Microsoft

Friday, June 11, 2010 10:13 AM by Johan Leino

Nice work!!

Loving your contributions to the community.

How is work progressing on the "jQuery Templates and Data Linking support"? I´m looking forward to using it...

# re: jQuery Globalization Plugin from Microsoft

Friday, June 11, 2010 10:17 AM by mike johnson

Nice work. nice post.

Curious when we went from calling this localization to globalization....

# re: jQuery Globalization Plugin from Microsoft

Friday, June 11, 2010 11:03 AM by Socrates470BC

Is this something that could be loaded on the edge servers?

# re: jQuery Globalization Plugin from Microsoft

Friday, June 11, 2010 11:05 AM by Andrew

Indonesian never shorten their months,

Januari, Februari, Maret, April, Mei, Juni, Juli, Agustus, September, Oktober, November, Desember

# re: jQuery Globalization Plugin from Microsoft

Friday, June 11, 2010 12:11 PM by RupW

Neat. However don't you need a jQuery.glob.index or similar in the package? That way you can filter the list of requested languages down to the set you have files for and even automatically load them in script. That way anyone who's configured xx-klingon as their first language can fall back to their second language and won't get failed web requests, and will also deal with tobi's injection concern (although the browser would have to be complicit in that).

Or this could be solved on the server-side, but it would make sense to distribute the index with the set of files too.

# re: jQuery Globalization Plugin from Microsoft

Friday, June 11, 2010 7:23 PM by Joseph

good info, will be used much.

# re: jQuery Globalization Plugin from Microsoft

Friday, June 11, 2010 9:02 PM by rich97

I don't know if Javascript is the way to go for critical body content. Doesn't .NET have a globalization library built in?

# re: jQuery Globalization Plugin from Microsoft

Saturday, June 12, 2010 3:11 AM by Will Scott

Hmm, I think you've made a mistake in this article. Your first image claims that the correct English currency symbol is $1,345.00

I think you'll find that the correct English symbol is £1345.00.

;-)

# re: jQuery Globalization Plugin from Microsoft

Saturday, June 12, 2010 8:24 AM by Chris

Very nice, now all that is needed is some way for JavaScript to be allowed to read the local machines globalisation settings so that it can know I've customised my short date format to yyyy-MM-dd

# re: jQuery Globalization Plugin from Microsoft

Sunday, June 13, 2010 1:09 AM by Tal

Great post, very useful and explaining!

# re: jQuery Globalization Plugin from Microsoft

Sunday, June 13, 2010 1:44 AM by Christophe - Path to SharePoint

Same comment as Mike Johnson: isn't this localization rather than globalization?

Well, nice move anyway.

# re: jQuery Globalization Plugin from Microsoft

Sunday, June 13, 2010 3:43 AM by ddredstar@hotmail.com

excellent plugin

# re: jQuery Globalization Plugin from Microsoft

Sunday, June 13, 2010 3:49 AM by Anthony Main

Greate jQuery plugin Scott really appreciating your teams contribution to the community. I wondered do you have a recommended plugin that will work along side the .net localisation stuff for full multiplingual support?

# re: jQuery Globalization Plugin from Microsoft

Sunday, June 13, 2010 7:57 AM by Tomas

Thanks.

Just a note: it would be better to use HTML5 tag <time> as date/time placeholder.

# re: jQuery Globalization Plugin from Microsoft

Sunday, June 13, 2010 10:48 AM by chintanpshah

Each application I develop is Multi-Language and this is great news for me. Also, Microsoft making contribution to jQuery is exiting too. Thanks for great news...

# re: jQuery Globalization Plugin from Microsoft

Sunday, June 13, 2010 12:54 PM by mfritsch

I had some errors in my logs using Request.UserLanguages[0]. I guess its because some crawlers or even users dont have defined a language. So I guess its better to check the length of UserLanguages first.

# re: jQuery Globalization Plugin from Microsoft

Sunday, June 13, 2010 6:30 PM by NetPotential

Excellent stuff.  Thanks for another great post Scott!

# re: jQuery Globalization Plugin from Microsoft

Monday, June 14, 2010 5:52 AM by Sam

I didnt got anythning from this

# re: jQuery Globalization Plugin from Microsoft

Monday, June 14, 2010 12:49 PM by Kamran

Just to let you know that it is not an Arabic calendar but an Islamic Calendar.

# re: jQuery Globalization Plugin from Microsoft

Monday, June 14, 2010 5:49 PM by Werbeagentur

Many thanks for share this post, this jquery plugin is very nice.

Just a note: it would be better to use HTML5 tag <time> as date/time placeholder.

# re: jQuery Globalization Plugin from Microsoft

Tuesday, June 15, 2010 1:29 PM by Swashbuckler

Nice, but what is the license?  I don't see it mentioned anywhere.

# re: jQuery Globalization Plugin from Microsoft

Wednesday, June 16, 2010 9:27 AM by Will

I agree with Glenn. This is plugin is great but shouldn't it have a namespace such as 'culture' that exposes all its methods?

# re: jQuery Globalization Plugin from Microsoft

Wednesday, June 16, 2010 3:56 PM by Ashu

Overall good stuff!

"patched datePicker"...Not good!

The datepicker plugin takes various regional settings to display localized values, so either make the globalization plugin smoothly work with it or work with the datepicker plugin team to make it work with the globalization plugin.

# re: jQuery Globalization Plugin from Microsoft

Friday, June 18, 2010 6:27 AM by DavidT

Awesome, perfect timing, I'm going to need this in the near future for a project that is starting soon.

# re: jQuery Globalization Plugin from Microsoft

Friday, June 18, 2010 12:31 PM by Nageswaran

Hi,

Thank you for this valuable information

# re: jQuery Globalization Plugin from Microsoft

Friday, June 18, 2010 1:03 PM by Rasul

Hi dear Scott, I love you and appreciate your efforts, but i want to say I'm living in Iran and I'm not a terrorist, I'm just a student like any other students in the world, as an Iranian i want to invite you to come here in my country and see our Hospitality, Culture, Knowledge and Love to other people, we can be very good friends and our government has no rights to interfere in our relationship, could you feel that it is too painful if you see this page when you want to download a free product:

" Thanks for your interest, but the product that you're trying to download is not available in your country"

I check your blog every day and love you but I'm so sorry because i didn't see my language: "Fa, fa" Persian language between these cultures.

I want to invite you here in my country "IRAN" to see the differences between us and Iraq; i hope that you agree with my invitation,

Sincerely yours,

Rasul

# re: jQuery Globalization Plugin from Microsoft

Saturday, June 19, 2010 3:34 AM by Colin Wiseman

Is there a way to remove the formating?  It's great that people can enter information in their own cultures, but when saving to the database, the ability to remove the culture back to a plain number format would be beneficial.

# re: jQuery Globalization Plugin from Microsoft

Thursday, June 24, 2010 2:33 AM by raweer

Please don't make code contributions to jquery you will just screw it up - let it be!

# re: jQuery Globalization Plugin from Microsoft

Sunday, June 27, 2010 3:45 PM by دردشة

Thursday, June 17, 2010 10:22 AM by Tiago

Hi,

I define culture to pt-PT, but if i use Firefox or chrome with datepicker plugin the return date is in English.

For example if i choose 10 June 2010, i get in controller 6 October 2010.

# re: jQuery Globalization Plugin from Microsoft

Monday, June 28, 2010 2:31 PM by Gift vincy

This plug in was very useful for us

# re: jQuery Globalization Plugin from Microsoft

Thursday, July 1, 2010 2:33 AM by jade

it's very useful !thanks for sharing

# re: jQuery Globalization Plugin from Microsoft

Monday, July 12, 2010 2:03 AM by adrift

Hi,

What about the currencies parsing ? Something like:

$.parseInt($.format(100, "c"), "c") === 100

Is that possible ?

# re: jQuery Globalization Plugin from Microsoft

Monday, August 2, 2010 4:25 PM by ethan

I downloaded the Demo and tried to integrate the minified version into my site (jQuery.glob.min.js) has errors. $.cultures.en is not defined -- so instead I used the non-minfied one.

# re: jQuery Globalization Plugin from Microsoft

Tuesday, August 3, 2010 9:14 AM by Bollywood

Scott, thanks for such a cool material.