JavaScript Date Object: LOCALE Methods to FORMAT the Date String

Basics of the Date Object in JavaScript Part 5: How to Use LOCALE FORMAT Methods

This article is a transcript of my free YouTube series about the basics of web development. If you prefer watching over reading, feel free to visit my channel “Dev Newbs”.

Hello developer friends! This will be our last trip together to uncover deep secrets of the built-in Javascript object Date. I will explain the last 3 methods that allow us to further specify the format of the Date output with respect to the locale of the client’s browser. Let’s begin.

The first method’s name is toLocaleString() and it returns a string with a language sensitive representation of the Date.

We have already come into contact with fairly new arguments “locale” and “options” that make it possible to specify language for the sake of formatting conventions of the given language.

The method has two input arguments. First is a string called “locale” and the second is an object called “options” that holds individual settings.

Return value of the method is of course Date string formatted according to provided language-specific conventions.

// default format of toString() method
console.log(new Date());
// Sat Jul 17 2021 22:10:00 GMT+0200 (stredoeurópsky letný čas)
// default locale of my browser, which is Slovak
console.log(new Date().toLocaleString());
// 17. 7. 2021, 22:10:00
// British English uses day-month-year order and 24-hour time without AM/PM
console.log(new Date().toLocaleString('en-GB', { timeZone: 'UTC' }));
// 17/07/2021, 20:10:00
// US English uses month-day-year order and 12-hour time with AM/PM
console.log(new Date().toLocaleString('en-US', { timeZone: 'UTC' }));
// 7/17/2021, 8:10:00 PM

If you do not specify any locale, the default one is used in its place. For me — it is ‘sk-SK’, which is Slovak locale. It has its own specifics like delimiters of the date part of Date object is dot followed by space and 24-hour time format.

Another two locales I wanted to show are the United States and Great Britain. They are similar, but different at the same time. The US follows the convention of month-day-year while most of the world follows the order of day-month-year. Also as it seems, the US likes to pad their numbers with zeros and they prefer 12hour AM/PM cycle over 24hour cycle of the remaining parts of the world.

The following block of code showcases the default format of multiple different locales.

// US English uses month-day-year order and 12-hour time with AM/PM
console.log(new Date().toLocaleString('en-US'));
// 7/17/2021, 10:10:00 PM
// British English uses day-month-year order and 24-hour time without AM/PM
console.log(new Date().toLocaleString('en-GB'));
// 17/07/2021, 22:10:00
// Germans use day.month.year order and 24-hour time without AM/PM
console.log(new Date().toLocaleString('de-DE'));
// 17.7.2021, 22:10:00
// Korean uses year-month-day order and 12-hour time with AM/PM
console.log(new Date().toLocaleString('ko-KR'));
// 2021. 7. 17. 오후 10:10:00
// Arabic in most Arabic speaking countries uses real Arabic digits
console.log(new Date().toLocaleString('ar-EG'));
// ١٧‏/٧‏/٢٠٢١, ١٠:١٠:٠٠ م

I chose 5 different locales — the US because it is obviously different from most of the others, Great Britain, German, Korean and Arabic. As you can see, each of them has its own specifics. The complete list of locales is quite large and contains several dozens of locales that should cover just about any language in the world.

The other possibility apart from using locales is to specify or even override the format defined by using locale. Options object has many different properties which allow us to modify the resulting format. I chose a few of them and showed them in the next code example.

let options = 
{ 
    weekday: 'long', 
    year: 'numeric', 
    month: 'long', 
    day: 'numeric',
    hour: '2-digit',
    minute: '2-digit',
    timeZone: 'UTC',
    timeZoneName: 'long'
};
console.log(new Date().toLocaleString('en-US', options));
// Saturday, July 17, 2021, 08:10 PM Coordinated Universal Time
console.log(new Date().toLocaleString('en-GB', options));
// Saturday, 17 July 2021, 20:10 Coordinated Universal Time
console.log(new Date().toLocaleString('de-DE', options));
// Samstag, 17. Juli 2021, 20:10 Koordinierte Weltzeit
console.log(new Date().toLocaleString('sk-SK', options));
// sobota 17. júla 2021, 20:10 koordinovaný svetový čas

Some of these options specify whether to output month as a number or a string. Others can specify timezone and its name or hour cycle. There are a lot of options and combinations, but from my experience, they are still not implemented consistently over the different browsers. So you have to try and see the specific property and decide whether it is worth using the options of the method, or to parse Date yourself and make necessary changes.

The next method carries the name toLocaleDateString() and it returns a string with a language sensitive representation of the date portion of this date. It can utilize “locales” and “options” just like the previous method.

let optionsDate = 
{ 
    weekday: 'long', 
    year: 'numeric', 
    month: 'long', 
    day: 'numeric'
};
console.log(new Date().toLocaleDateString());
// 17. 7. 2021
console.log(new Date().toLocaleDateString('en-US'));
// 7/17/2021
console.log(new Date().toLocaleDateString('en-GB'));
// 17/07/2021
console.log(new Date().toLocaleDateString(undefined, optionsDate));
// sobota 17. júla 2021
console.log(new Date().toLocaleDateString('en-US', optionsDate));
// Saturday, July 17, 2021
console.log(new Date().toLocaleDateString('en-GB', optionsDate));
// Saturday, 17 July 2021

In the case of this method, you have available the exact same properties and possibilities as with the toLocaleString() method. However it only makes sense to use the portion of settings that somehow modifies the date portion of the provided Date object.

The last method is toLocaleTimeString() which returns a string with a language-sensitive representation of the time portion of the date. Exactly like with two previous methods, also this one has locales and options available to further modify the resulting string.

let myTime = new Date(2021, 6, 8, 23, 15, 47);
console.log(myTime.toLocaleTimeString());
// 23:15:47
console.log(myTime.toLocaleTimeString('en-US'));
// 11:15:47 PM
console.log(myTime.toLocaleTimeString('en-GB'));
// 23:15:47
console.log(myTime.toLocaleTimeString('sk-SK', { timeZone: 'CET', timeZoneName: 'long' }));
// 23:15:47 GMT+02:00
console.log(myTime.toLocaleTimeString('en-US', { hour12: false, timeZone: 'GMT' }));
// 21:15:47
console.log(myTime.toLocaleTimeString('en-GB', { hour: '2-digit', minute: '2-digit' }));
// 23:15

We can specify a certain format of the output and properties like 12 or 24 hour cycle for the display of time portion. We can also completely override the format defined by locale using the options properties. We can for example force the US locale to use a 24-hour cycle for displaying time. And of course, the possibilities don’t end there. Sky’s the limit, but tread carefully, because just like with the previous method, also this one allows you to add portions of the Date object that don’t exactly fit with the time portion.

And with that, we are done. Those are all the Date object methods covered one by one. Now you are one step closer to becoming a real Javascript expert. Or, you know, a somewhat decent programmer. Definitely one of those two.

But jokes aside — thank you if you stuck with me till the end. I hope you learned something new. I will hopefully see you soon with the next Javascript Basics series. This time maybe about Numbers? Who knows.

More content at plainenglish.io