Локализация дат и времени

Для локализации дат и времени в JavaScript применяется объект Intl.DateTimeFormat. Его конструктор может принимать два параметра:

Intl.DateTimeFormat([locales[, options]])

Параметр locales представляет код языка в формате BCP 47 или набор языковых кодов.

Параметр options представляет дополнительный набор опций:

• dateStyle: определяет стиль форматирования даты. Возможные значения:

  • "full"

  • "long"

  • "medium"

  • "short"

• timeStyle: определяет стиль форматирования времени. Возможные значения:

  • "full"

  • "long"

  • "medium"

  • "short"

• calendar: задает календарь. Возможные значения: "buddhist", "chinese", " coptic", "ethiopia", "ethiopic", "gregory", " hebrew", "indian", "islamic", "iso8601", "japanese", "persian", "roc"

• numberingSystem: задает применяемую систему чисел. Возможные значения: "arab", "arabext", " bali", "beng", "deva", "fullwide", " gujr", "guru", "hanidec", "khmr", " knda", "laoo", "latn", "limb", "mlym", " mong", "mymr", "orya", "tamldec", " telu", "thai", "tibt"

• dayPeriod: формат периода суток. Возможные значения: "narrow", "short", " long".

• timeZone: временная зона.

• hour12: указывает, будет ли использоваться 12-часовой формат (значение true) или 24-часовой формат (значение false) .

• hourCycle: часовой цикл. Возможные значения: "h11", "h12", "h23", "h24".

• formatMatcher: устанавливает алгоритм сопоставления формата даты/времени. Возможные значения: "basic" и "best fit" (значение по умолчанию).

• weekday: определяет формат дня недели. Возможные значения:

  • "long" (например, Thursday)

  • "short" (например, Thu)

  • "narrow" (например, T - сокращение от Thursday)

• era: определяет формат вывода эры. Возможные значения:

  • "long" (например, Anno Domini)

  • "short" (например, AD)

  • "narrow" (например, A)

• year: определяет формат года. Возможные значения:

  • "numeric" (число полностью, например, 2021)

  • "2-digit" (выводит только две последних цифры)

• month: определяет формат месяца. Возможные значения:

  • "numeric" (например, 2)

  • "2-digit" (в виде двухцифрового кода, например, 02)

  • "long" (например, March)

  • "short" (например, Mar)

  • "narrow" (например, M)

• day: определяет, как выводится номер дня. Возможные значения:

  • "numeric" (например, 2)

  • "2-digit" (в виде двухцифрового кода, например, 02)

• hour: задает формат вывода часа. Возможные значения: "numeric" и "2-digit"

• minute: задает формат вывода минуты. Возможные значения: "numeric" и "2-digit"

• second: задает формат вывода секунды. Возможные значения: "numeric" и "2-digit"

• fractionalSecondDigits: определяет формат вывода долей секунды. Возможные значения:

  • 0 (доли секунды не выводятся)

  • 1 (выводится только первая цифра долей секунды, например, при значении 736 выводится 7)

  • 2 (выводятся только две первых цифра долей секунды, например, при значении 736 выводится 73)

  • 3 (выводятся три цифры долей секунды, например, при значении 736 выводится 736)

• timeZoneName: определяет представление наименования часового пояса. Возможные значения:

  • "long" (полное название, например, "Pacific Standard Time, Nordamerikanische Westküsten-Normalzeit")

  • "short" (короткое название, например, PST, GMT-8)

  • "longOffset" (полное название в формате GMT, например, "GMT-8")

  • "shortOffset" (короткое название в формате GMT , например, "GMT-0800")

  • "longGeneric" (полный обобщенный формат, например, "Pacific Time, Nordamerikanische Westküstenzeit")

  • "shortGeneric" (короткий обобщенный формат, например, "PT, Los Angeles Zeit")

Для форматирования даты объект Intl.DateTimeFormat предоставляет метод format(), в который передается форматируемая дата - объект Date.

Рассмотрим несколько примеров:

const now = new Date();
const ruDate = new Intl.DateTimeFormat("ru").format(now);
console.log(ruDate);	// 16.11.2023
const enDate = new Intl.DateTimeFormat("en").format(now);
console.log(enDate);	// 11/16/2023

В данном случае в конструктор Intl.DateTimeFormat передается значение только для первого параметра locales. В первом случае это код "ru", который представляет русскоязычную культуру, а во втором случае код "en" - англоязычная культура. И в зависимости от переданного кода культуры мы получим разные результаты при форматировании даты.

Форматирование даты

По умолчанию метод format() возвращает дату в сокращенном формате, то есть фактически применяя настройку {dateStyle: "short"}. С помощью параметра dateStyle мы можем настроить вывод даты. Посмотрим, какие варианты вывода дат нам предоставляет объект Intl.DateTimeFormat на примере русскоязычной культуры:

const now = new Date();
const shortDate = new Intl.DateTimeFormat("ru", {dateStyle: "short"}).format(now);
console.log(shortDate);		// 12.09.2021
const mediumDate = new Intl.DateTimeFormat("ru", {dateStyle: "medium"}).format(now);
console.log(mediumDate);	// 12 сент. 2021 г.
const longDate = new Intl.DateTimeFormat("ru", {dateStyle: "long"}).format(now);
console.log(longDate);		// 12 сентября 2021 г.
const fullDate = new Intl.DateTimeFormat("ru", {dateStyle: "full"}).format(now);
console.log(fullDate);		// воскресенье, 12 сентября 2021 г.

Форматирование времени

По умолчанию метод format() не выводит время. С помощью параметра timeStyle настроим вывод времени на примере русскоязычной культуры:

const now = new Date();
const shortTime = new Intl.DateTimeFormat("ru", {timeStyle: "short"}).format(now);
console.log(shortTime);		// 20:42
const mediumTime = new Intl.DateTimeFormat("ru", {timeStyle: "medium"}).format(now);
console.log(mediumTime);	// 20:42:08
const longTime = new Intl.DateTimeFormat("ru", {timeStyle: "long"}).format(now);
console.log(longTime);		// 20:42:08 GMT+11
const fullTime = new Intl.DateTimeFormat("ru", {timeStyle: "full"}).format(now);
console.log(fullTime);		// 20:42:08 GMT+11:00

Объединение даты и времени

Если мы используем только настройку dateStyle, то выводится возвращается только дата. Если применяется настройка timeStyle, то возвращается только время. Чтобы возвратить и дату, и время, необходимо установить обе настройки:

const now = new Date();
const shortDateTime = new Intl.DateTimeFormat("ru", {dateStyle: "short", timeStyle: "short"}).format(now);
console.log(shortDateTime);		// 12.09.2021, 20:43

Остальные настройки

При необходимости мы можем использовать остальные настройки. Например, если необходимо применить арабскую систему чисел, то мы можем настроить вывод чисел с помощью параметра numberingSystem:

const now = new Date();
const arDateTime1 = new Intl.DateTimeFormat("ar", {dateStyle: "short", timeStyle: "short"}).format(now);
console.log(arDateTime1);		// 12‏/9‏/2021 8:51 م
const arDateTime2 = new Intl.DateTimeFormat("ar", {dateStyle: "short", timeStyle: "short", numberingSystem: "arab"}).format(now);
console.log(arDateTime2);		// ١٢‏/٩‏/٢٠٢١ ٨:٥٠ م

Если приложение рассчитано на среду, где действует другой календарь, то можно задать параметр calendar:

const now = new Date();
const persianDateTime = new Intl.DateTimeFormat("fa", {dateStyle: "long", numberingSystem: "arab", calendar: "persian"}).format(now);
console.log(persianDateTime);		// ٢١ شهریور ١٤٠٠
const zhDateTime = new Intl.DateTimeFormat("zh", {dateStyle: "long", calendar: "chinese"}).format(now);
console.log(zhDateTime);			// 2021辛丑年八月初六

Методы Date

Следует отметить, что тип Date также предоставляет ряд методов для локализации даты и времени:

• toLocaleString()

• toLocaleDateString()

• toLocaleTimeString()

В качестве параметра эти методы принимают локаль, в которую надо локализовать дату и время:

const now = new Date();
console.log(now.toLocaleString("en"));		// 11/16/2023, 9:17:25 PM
console.log(now.toLocaleTimeString("en"));  // 9:17:25 PM
console.log(now.toLocaleDateString("en"));  // 11/16/2023

console.log(now.toLocaleString("ru"));      // 16.11.2023, 21:17:25
console.log(now.toLocaleTimeString("ru"));  // 21:17:25
console.log(now.toLocaleDateString("ru"));  // 16.11.2023