Locale-Sensitive JavaScript Method

date.toLocaleString();
date.toLocaleString(locales);
date.toLocaleString(locales, options);
number.toLocaleString();
number.toLocaleString(locales);
number.toLocaleString(locales, options);


Internationalization (I18n) Method Overview

The toLocaleString method returns the date/time of the date object, or the formatted number of the number object, in either the system's locale or the specified locale passed into the method. The options parameter can be used to customize the format, including setting the time zone or indicating the number should be displayed as a currency.

Date formatting example:

var date = new Date();
var options = {timeZone: "America/New_York", timeZoneName: "long"};
var result1 = date.toLocaleString("en-US", options);
var result2 = date.toLocaleString("de-DE", options);

Results are:

result1: 9/17/2014 1:14:44 PM Eastern Daylight Time
result2: 17.9.2014 13:15:33 Nordamerikanische Ostküsten-Sommerzeit


Number formatting example:

var number = 123.567;
var options = {maximumFractionDigits: 2};
var result1 = number.toLocaleString("en-US", options);
var result2 = number.toLocaleString("de-DE", options);

Results are:

result1: 123.57 // English (U.S.) uses period for decimal separator
result2: 123,57 // German (Germany) uses comma for decimal separator


For additional details on date.toLocaleString click here (w3schools) and here (MDN).

For additional details on number.toLocaleString click here (MDN).

I18n Issues

Whether or not calling toLocaleString is an i18n issue is dependent on how it is being used in the application. Some possible issues are:

• There is no locales parameter passed into the method, which means the system's locale will be used to format the date/time or number.
• There is no timeZone option passed into the method, which means the system's local time zone will be used to format the date/time or number.
• You want a fixed date format, regardless the locale. One reason might be that this date/time string is stored in a log file that is to remain in U.S. English.
• You want a fixed number format, regardless the locale. One reason might be that this number string is stored in a log file that is to remain in U.S. English.
• A large set of dates or numbers are being formatted to date/time strings and you want to improve the performance.

Suggested Replacement

Make sure that you pass in the application's locale so that the date or number will be formatted correctly. In addition, in the case of dates, ensure that the timeZone option is set to the correct time zone and that the timeZoneName option is included if you want to display the time zone. Set other options to customize the locale-sensitive format.

If you want a fixed date or number format, regardless the locale, you could call toString, which will format the date/time or number using U.S. English. For dates, you can also call toISOString to format the date in a locale-independent way; the resulting ISO Standard date/time string is understandable in all locales.

To improve performance, call Intl.DateTimeFormat constructor for dates or Intl.NumberFormat constructor for numbers, which returns a locale-sensitive format object that you can then repeatedly call its format method.

Globalyzer will detect this method and report it as an i18n issue. If you have determined that the call is being handled correctly, you can use Globalyzer's Ignore Comment functionality to ensure that it isn't picked up in a subsequent scan.