toLocaleString()

ES1+

Returns a string with a language-sensitive representation of this date.

Syntax

date.toLocaleString(locales, options)

Parameters

locales string | Array optional

A string with a BCP 47 language tag, or an array of such strings

options Object optional

An object with configuration properties

Return Value

string

A string representing the date

Examples

JavaScript

const date = new Date('2024-01-15T14:30:00');
console.log(date.toLocaleString('ko-KR'));
console.log(date.toLocaleString('en-US'));
console.log(date.toLocaleString('ja-JP'));

Output:

// '2024. 1. 15. 오후 2:30:00' '1/15/2024, 2:30:00 PM' '2024/1/15 14:30:00'

📌 When to Use

Use toLocaleString() for user-facing date/time displays that should respect the users language and regional formatting preferences.

⚠️ Common Mistakes

Not providing locale when consistent formatting is needed - results vary by browser/OS default.

Using toLocaleString() for data storage instead of toISOString() - locale strings are not reliably parseable.

✅ Best Practices

Use Intl.DateTimeFormat for repeated formatting - it is faster than toLocaleString() with options.

Specify explicit options for consistent output: { dateStyle: "full", timeStyle: "short" }.

⚡ Performance Notes

toLocaleString() with options creates an Intl.DateTimeFormat internally. For multiple dates, create a reusable formatter: new Intl.DateTimeFormat(locale, options).format(date).

🌍 Real World Example

Multilingual Date Display

Display dates in user-preferred format based on their language settings.

function formatEventDate(date, locale, options = {}) {
  const defaultOptions = {
    weekday: 'long',
    year: 'numeric',
    month: 'long',
    day: 'numeric',
    hour: '2-digit',
    minute: '2-digit'
  };

  const mergedOptions = { ...defaultOptions, ...options };
  const eventDate = new Date(date);

  return {
    formatted: eventDate.toLocaleString(locale, mergedOptions),
    relative: getRelativeTime(eventDate, locale)
  };
}

function getRelativeTime(date, locale) {
  const rtf = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' });
  const diff = date - new Date();
  const days = Math.round(diff / (1000 * 60 * 60 * 24));
  return rtf.format(days, 'day');
}

console.log(formatEventDate('2024-03-20T14:00:00', 'ko-KR'));
// { formatted: '2024년 3월 20일 수요일 오후 02:00', relative: '5일 후' }

Related Methods

toLocaleDateString()