The toLocaleString() method returns a string with a language-sensitive date representation. In most cases, this method converts the date and time to a string using the system locales. Let’s take a closer look.

Introduction to toLocaleString()

Language-sensitive representation of numbers implies this method helps convert currencies, time, and other variables depending on the input data you set. Syntax in code looks like this:

toLocaleString()
toLocaleString(locales)
toLocaleString(locales, options)

The first line of code shows the usual appearance of the toLocaleString() method. As for locales and options, these two parameters deserve separate explanations:

  • locales - is an optional parameter, a string specifying which language-specific format to pick

  • options - is also an optional parameter, which serves as an object with configuration properties

The proper use of locales and options helps tweak the overall behavior of the method. However, if you omit these parameters altogether, the form of the string returned will be solely implementation-dependent.

Alright, let’s review the most basic example of using the toLocaleString() method. Let’s omit using locales as of now, and assign a new date, which will be showing the following date and time: 7/6/2022, 12:00:00 PM.

let date = new Date(Date.UTC(2022, 06, 06, 12, 0, 0));
console.log(date.toLocaleString()); // Expected output: 7/6/2022, 12:00:00 PM

This example is fairly easy since it shows the UTC date, while the numbers corresponding to date and time are separated by commas. Please note that the default input options are returned in the date/time format if you don't use locales and options.

Experimenting with locales

Because the two optional parameters are crucial for the toLocaleString() method, it’s smart to make the most of them. Let’s experiment with locales to see how you can use them to work with date/time values. Because the method heavily relies upon the system application data, the following example is shown without the expected output:

let date = new Date(Date.UTC(2022, 06, 06, 12, 0, 0));
console.log(date.toLocaleString()); // Expected output: 7/6/2022, 12:00:00 PM
console.log(date.toLocaleString('en-GB'));
console.log(date.toLocaleString('ko-KR'));
console.log(date.toLocaleString(`fr-FH`));

In this case, we add the locales value of countries, such as Great Britain, the Republic of Korea, and France. The expected output for the time/date input values will depend on your local application configurations. Still, the time/date outputs will assume the respective locations and return the corresponding values.

Currencies

toLocaleString() helps get the locale-sensitive representations when working with number values. By far, the best example to illustrate this method’s usefulness is the work with currencies. Let’s assign a number and try to get the respective currency representations:

const number = 654555;

console.log(number.toLocaleString('en-US', {
style: 'currency',
currency: 'USD'
})); // Expected output: $12,345.68

console.log(number.toLocaleString('hi-IN', {
style: 'currency',
currency: 'INR'
})); // Expected output: ₹12,345.68

The style and currency parameters were also added for a proper representation of currency values. This code snippet represents how the toLocaleString() method shows the same const number value, only this time with a respective currency mode.

Don’t forget that you can add more countries to the code. Let’s add France and see how the expected output will modify itself:

const number = 654555;

console.log(number.toLocaleString('fr-FR', {
style: 'currency',
currency: 'EUR'
})); // Expected output: €654,555.00

Feel free to experiment with currencies since the toLocaleString() is quite flexible for such tasks. For a proper representation of country and currency codes, see the recent ISO Standards.

Working with arrays

Another great way to make the most of toLocaleString() is to use it with arrays. Let’s use both locales and options to see how the described method behaves with different data types within an array:

const arr = [12345678, new Date(), "alligators"];
console.log(arr.toLocaleString(`fr-FR`,{
style: 'currency',
currency: 'EUR',
era: 'long'
})); // Expected output: 12 345 678,00 €,10 11 2019 après Jésus-Christ à 18:30:03,alligators

const arr2 = [12345678, new Date(), "alligators"];
console.log(arr.toLocaleString(`en-US`,{
style: 'currency',
currency: 'USD',
era: 'long'
})); // Expected output: $12,345,678.00,11 10, 2019 Anno Domini, 6:31:56 PM,alligators

As you see, we’ve used not only style and currency, but also era. When you use the usual input data, the toLocaleString() method returns different outputs depending on the countries you’ve specified. In particular, the French and English versions of the era are depicted in this example. And don’t forget that the currencies match the country’s-locale representations.

Test yourself

  • Task 1. Use the toLocaleString() method without locales and options to show the CST time with the corresponding values: 2022, 07, 12, 16, 0, 0. Log the result through a console:

Solution:

let date = new Date(Date.CST(2022, 07, 12, 16, 0, 0));
console.log(date.toLocaleString()); // Expected output: 8/12/2022, 4:00:00 PM

  • Task 2. Using the same date values as in Task 1, use the toLocaleString() method and add the locale-specific time zones of India and France. In the expected output, estimate the corresponding time for these two time zones and log them through a console:

Solution:

let date = new Date(Date.CST(2022, 07, 12, 16, 0, 0));
console.log(date.toLocaleString()); // Expected output: 8/12/2022, 4:00:00 PM
console.log(date.toLocaleString('hi-IN')); // Expected output: 9/12/2022, 01:30:00 AM
console.log(date.toLocaleString(`fr-FR`)); // Expected output: 8/12/2022, 11:00:00 PM

  • Task 3. Create a number 8584 and use the toLocaleString() method with options and values to represent it in French and Indian currencies. As for the initial input, use the American dollars. Then, log the results through a console:

const number = 8584;

console.log(number.toLocaleString('en-US', {
style: 'currency',
currency: 'USD'
})); // Expected output: $8,584.00

console.log(number.toLocaleString('hi-IN', {
style: 'currency',
currency: 'INR'
})); // Expected output: ₹8,584.00

console.log(number.toLocaleString('fr-FR', {
style: 'currency',
currency: 'EUR'
})); // Expected output: €8,584.00