Dates are often used as case studies to illustrate the risks of ignoring cultural differences. For example, the date 4/7/2011 could be taken to mean July 4th by some and April 7th by others.

Fortunately, the open source JavaScript library Globalize provides a relatively easy way of delivering properly formatted dates (and other culture-specific data types) to users anywhere around the world.

In this article, I will show you how JavaScript’s built-in functions may be used to display dates and their inherent limitations and inconsistencies. I will then turn to Globalize to avoid these issues.

The not-so-simple approach to dates

Using the toString, toDateString or toTimeString

The simplest way to write a Date value would be to use the toString method, such as today.toString(). It produces, by definition, a system-defined presentation of the date.

In practice, you get some English-language notation, such as “Sat Jul 04 2015 13:30:50 GMT+0300,” independently of the language of the page, or the browser, or anything. However, browsers may try to localize the time zone denotation in their own ways. The code document.write(new Date(2115,6,11)) gives different results based on different browsers. The following examples are from browsers on a Finnish version of Windows 7 Pro:

Internet Explorer: Thu Jul 11 00:00:00 UTC+0300 2115
Firefox: Thu Jul 11 2115 00:00:00 GMT+0300 (Suomen kesaaika)
Opera: Thu Jul 11 2115 00:00:00 GMT+0300
Chrome: Thu Jul 11 2115 00:00:00 GMT+0300 (Suomen kes�aika)
Safari: Thu Jul 11 2115 00:00:00 GMT+0300 (Suomen kesäaika)
Android: Thu Jul 11 2115 00:00:00 GMT+0300 (EST)

So three of the six browsers write the time zone using a name in the language of the underlying operating system. Only Safari gets it right; Firefox and Chrome mess up the letter “ä” in two different ways.

The best we can say about the toString method for Date is that it produces some human-readable presentation of the moment of time. The presentation is widely understood, but far from universally. It would not look good on a page otherwise in Greek, Chinese, or Thai.

Similar challenges apply to using the methods toDateString and toTimeString.

Beware of implicit Date toString conversions

In JavaScript, toString() often gets applied implicitly. For example, if the value of foo is a Date object, then any of the following statements causes a call to toString:

alert(foo);
document.write(foo);
document.getElementById('x').innerHTML = foo;
foo = foo + '';

Automatic conversion to strings are often a convenience, and many authors routinely make use of it, perhaps even without ever thinking about it. Thus, it is not always obvious from the code where data gets written in a manner that should be modified when localizing software. The convenience of automatic operations in JavaScript has drawbacks, too. The implicit conversion (or coercion) means that general, non-localized toString() methods are used.

The deceptive toLocaleDateString

It would be natural to expect that the toLocaleDateString method produces a localized presentation of the date, and it does. But, as a developer, the locale is beyond your control. Little does it help to have the date localized in Swahili when it should be in Arabic.

You may also get essentially different results on different browsers even with the same system. For example, writing a date on a Finnish Windows operating system, with user interface language set to French, I get:

Internet Explorer: dimanche 1 juillet 2012
Firefox: 11. heinäkuuta 2012
Opera: 11/07/2012

Globalize to the rescue

To localize the display of Date values, you could override the built-in toString method. For that, you would need code that converts a Date value to a localized string in a format that is suitable for the target locale.

Using the Globalize library, this would be easy:

Date.prototype.toString = function() {
return Globalize.format(this,'F'); }

This example uses a full-length (‘F’) format, which contains all of the date information. In many contexts, it would be better to display only subsets of this information, such a short date. To get more granular control, we need specific presentation formats, which we cover in more detail in Part II. But this code is an effective and lightweight way to protect against accidental non-localized writing of Date values.

Now suppose you have written, say, var today = new Date() in JavaScript. How would you display the date in a format that is understandable and unambiguous to the user? Let us first assume, for simplicity, that we know that the user is German-speaking and that a “long” or “full” format is to be used for the date.

Using the Globalize library, you could write the following:

<!doctype html>
<title>Globalize demo<title>
<meta charset=utf-8>
<body>
<p id=date></p>
<script type="text/javascript" src="globalize.js">
</script>

In the example above, the first two script elements are needed to refer to external library files. The files are assumed to reside in the same folder as the page, so that you can use just filenames as URLs. The files referred to can be downloaded via the Globalize page at GitHub. The page address still reflects the old name “jQuery Global” of the library, but the Globalize library is now totally independent of jQuery, though it reflects same general idea “write less, do more.” Using Globalize by no means excludes using jQuery, but neither does it require it.

The code uses the “plain” way of accessing an element with getElementById() and setting its innerHTML property. If you are used to jQuery, you would probably want to replace the assignment with a shorter construct:

$('#date').html(Globalize.format(today,'D','de'));

Depending on the actual date, the web page would display:

Mittwoch, 25. Mai 2011

And you didn’t need to know a single word of German to produce this text string.

Article excerpted from Going Global with JavaScript and Globalize.js by Jukka Korpella.