js-joda-locale

Библиотека js-joda предоставляет мощную реализацию API даты и времени, вдохновлённую Java Time API (java.time). Базовая часть библиотеки ориентирована на точную работу с датами, временем, часовыми поясами и временными интервалами, однако практически не содержит средств локализации.

Пакет js-joda-locale добавляет:

поддержку локалей;
форматирование дат в соответствии с региональными стандартами;
локализованные названия месяцев и дней недели;
поддержку языковых настроек;
интеграцию с Intl;
корректное отображение дат для различных культур.

Без js-joda-locale форматирование ограничивается шаблонами и англоязычными значениями. После подключения пакета становятся доступны полноценные механизмы интернационализации.

Установка

Установка базовых пакетов

npm install @js-joda/core
npm install @js-joda/locale

Для работы с часовыми поясами дополнительно используется:

npm install @js-joda/timezone

Подключение библиотеки

CommonJS

const { LocalDate, DateTimeFormatter } = require('@js-joda/core');
require('@js-joda/locale_ru');

ES Modules

import { LocalDate, DateTimeFormatter } from '@js-joda/core';
import '@js-joda/locale_ru';

Архитектура локализации

Система локализации в js-joda построена вокруг:

Locale
DateTimeFormatter
DecimalStyle
TextStyle
ResolverStyle

Основной объект — DateTimeFormatter, который умеет:

форматировать дату;
учитывать локаль;
выводить текстовые значения;
интерпретировать региональные стандарты.

Подключение локали

Каждая локаль подключается отдельным модулем.

Русская локаль

import '@js-joda/locale_ru';

Немецкая локаль

import '@js-joda/locale_de';

Французская локаль

import '@js-joda/locale_fr';

Такой подход уменьшает размер итогового бандла.

Использование Locale

Создание локали

import { Locale } from '@js-joda/locale';

const locale = Locale.forLanguageTag('ru');

Английская локаль

const locale = Locale.forLanguageTag('en-US');

Немецкая локаль

const locale = Locale.forLanguageTag('de-DE');

Форматирование даты с локалью

Базовый пример

import {
    LocalDate,
    DateTimeFormatter
} from '@js-joda/core';

import { Locale } from '@js-joda/locale';
import '@js-joda/locale_ru';

const date = LocalDate.of(2025, 3, 18);

const formatter = DateTimeFormatter
    .ofPattern('d MMMM yyyy')
    .withLocale(Locale.forLanguageTag('ru'));

console.log(date.format(formatter));

Результат:

18 марта 2025

Форматирование дня недели

Полное название

const formatter = DateTimeFormatter
    .ofPattern('EEEE')
    .withLocale(Locale.forLanguageTag('ru'));

console.log(date.format(formatter));

Результат:

вторник

Краткое название

const formatter = DateTimeFormatter
    .ofPattern('EEE')
    .withLocale(Locale.forLanguageTag('ru'));

Результат:

вт

Форматирование месяца

Полное название месяца

const formatter = DateTimeFormatter
    .ofPattern('MMMM')
    .withLocale(Locale.forLanguageTag('ru'));

Результат:

март

Сокращённое название месяца

const formatter = DateTimeFormatter
    .ofPattern('MMM')
    .withLocale(Locale.forLanguageTag('ru'));

Результат:

мар.

Таблица основных шаблонов

Шаблон	Описание	Пример
`d`	День месяца	5
`dd`	День с нулём	05
`M`	Номер месяца	3
`MM`	Месяц с нулём	03
`MMM`	Краткий месяц	мар.
`MMMM`	Полный месяц	марта
`yy`	Короткий год	25
`yyyy`	Полный год	2025
`E`	Краткий день недели	вт
`EEEE`	Полный день недели	вторник

Отличия MMM и MMMM

MMM

DateTimeFormatter.ofPattern('MMM')

Выводит краткое название:

мар.

MMMM

DateTimeFormatter.ofPattern('MMMM')

Выводит полную форму:

марта

Работа с LocalDateTime

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

import {
    LocalDateTime,
    DateTimeFormatter
} from '@js-joda/core';

const dateTime = LocalDateTime.of(
    2025,
    7,
    21,
    14,
    35
);

const formatter = DateTimeFormatter
    .ofPattern('d MMMM yyyy HH:mm')
    .withLocale(Locale.forLanguageTag('ru'));

console.log(dateTime.format(formatter));

Результат:

21 июля 2025 14:35

Использование разных локалей

Русский язык

const ru = Locale.forLanguageTag('ru');

Английский язык

const en = Locale.forLanguageTag('en-US');

Французский язык

const fr = Locale.forLanguageTag('fr-FR');

Сравнение локалей

Русский

18 марта 2025

Английский

March 18, 2025

Немецкий

18. März 2025

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

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

import { LocalTime } from '@js-joda/core';

const time = LocalTime.of(9, 45);

const formatter = DateTimeFormatter
    .ofPattern('HH:mm')
    .withLocale(Locale.forLanguageTag('ru'));

console.log(time.format(formatter));

Использование 12-часового формата

Формат hh:mm a

const formatter = DateTimeFormatter
    .ofPattern('hh:mm a')
    .withLocale(Locale.forLanguageTag('en-US'));

Результат:

09:45 AM

Использование 24-часового формата

const formatter = DateTimeFormatter
    .ofPattern('HH:mm');

Результат:

21:45

Локализованные стили форматирования

FormatStyle позволяет использовать готовые региональные шаблоны.

Импорт

import {
    DateTimeFormatter,
    FormatStyle
} from '@js-joda/core';

FULL

Пример

const formatter = DateTimeFormatter
    .ofLocalizedDate(FormatStyle.FULL)
    .withLocale(Locale.forLanguageTag('ru'));

Результат:

вторник, 18 марта 2025 г.

LONG

DateTimeFormatter.ofLocalizedDate(FormatStyle.LONG)

Пример:

18 марта 2025 г.

MEDIUM

DateTimeFormatter.ofLocalizedDate(FormatStyle.MEDIUM)

Пример:

18 мар. 2025 г.

SHORT

DateTimeFormatter.ofLocalizedDate(FormatStyle.SHORT)

Пример:

18.03.2025

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

Использование ofLocalizedDateTime

const formatter = DateTimeFormatter
    .ofLocalizedDateTime(FormatStyle.MEDIUM)
    .withLocale(Locale.forLanguageTag('ru'));

Работа с ZonedDateTime

Форматирование даты с часовым поясом

import {
    ZonedDateTime,
    ZoneId
} from '@js-joda/core';

const zoned = ZonedDateTime.now(
    ZoneId.of('Europe/Moscow')
);

const formatter = DateTimeFormatter
    .ofPattern('dd MMMM yyyy HH:mm z')
    .withLocale(Locale.forLanguageTag('ru'));

console.log(zoned.format(formatter));

Форматирование часового пояса

Символ z

'z'

Пример результата:

MSK

Символ O

'O'

Пример:

GMT+3

Использование TextStyle

TextStyle определяет формат текстового представления.

SHORT

TextStyle.SHORT

Пример:

пн

FULL

TextStyle.FULL

Пример:

понедельник

Локализация через Intl

Внутри js-joda-locale активно используется API Intl.

Это обеспечивает:

поддержку большого количества языков;
региональные стандарты;
корректные форматы;
совместимость с браузерами.

Совместимость среды выполнения

Node.js

Полная поддержка доступна в современных версиях Node.js.

Браузеры

Поддерживаются:

Chrome
Firefox
Edge
Safari

При использовании старых браузеров может потребоваться полифилл Intl.

Особенности русского языка

Русская локаль имеет несколько грамматических особенностей.

Склонение месяцев

18 марта

но:

март

Это зависит от шаблона форматирования.

Номинативная форма месяца

DateTimeFormatter.ofPattern('LLLL')

Результат:

март

Родительный падеж

DateTimeFormatter.ofPattern('MMMM')

Результат:

марта

Парсинг локализованных дат

Пример парсинга

const formatter = DateTimeFormatter
    .ofPattern('d MMMM yyyy')
    .withLocale(Locale.forLanguageTag('ru'));

const date = LocalDate.parse(
    '18 марта 2025',
    formatter
);

console.log(date.toString());

Ошибки локализации

Локаль не подключена

import '@js-joda/locale_ru';

Без подключения локали форматирование может завершиться ошибкой или использовать английские значения.

Неверный language tag

Ошибка

Locale.forLanguageTag('russian')

Правильно

Locale.forLanguageTag('ru')

Часто используемые language tags

Язык	Тег
Русский	ru
Английский	en-US
Немецкий	de-DE
Французский	fr-FR
Испанский	es-ES
Китайский	zh-CN
Японский	ja-JP

Практический пример локализованного форматирования

import {
    LocalDateTime,
    DateTimeFormatter
} from '@js-joda/core';

import { Locale } from '@js-joda/locale';

import '@js-joda/locale_ru';
import '@js-joda/locale_en';

const formatterRu = DateTimeFormatter
    .ofPattern('d MMMM yyyy HH:mm')
    .withLocale(Locale.forLanguageTag('ru'));

const formatterEn = DateTimeFormatter
    .ofPattern('MMMM d, yyyy h:mm a')
    .withLocale(Locale.forLanguageTag('en-US'));

const date = LocalDateTime.now();

console.log(date.format(formatterRu));
console.log(date.format(formatterEn));

Оптимизация размера бандла

Подключение только нужных локалей

Правильно:

import '@js-joda/locale_ru';

Нежелательно:

import '@js-joda/locale';

Подключение всех локалей значительно увеличивает размер сборки.

Использование immutable-объектов

Все объекты js-joda неизменяемы.

const formatter1 = DateTimeFormatter.ofPattern('dd.MM.yyyy');

const formatter2 = formatter1.withLocale(
    Locale.forLanguageTag('ru')
);

Исходный объект не изменяется.

Интеграция с frontend-frameworks

React

const formatter = DateTimeFormatter
    .ofPattern('d MMMM yyyy')
    .withLocale(Locale.forLanguageTag('ru'));

Vue

date.format(formatter)

Angular

DateTimeFormatter.ofLocalizedDate(
    FormatStyle.LONG
)

Кэширование форматтеров

Создание DateTimeFormatter — относительно дорогая операция.

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

const formatter = DateTimeFormatter
    .ofPattern('d MMMM yyyy')
    .withLocale(Locale.forLanguageTag('ru'));

Сравнение с native Date

Проблемы Date

мутабельность;
сложная работа с часовыми поясами;
нестабильный парсинг;
неявные преобразования.

Преимущества js-joda

immutable API;
строгие типы даты и времени;
предсказуемое форматирование;
безопасный парсинг;
качественная локализация;
API уровня Java Time.

Структура пакетов локализации

Пакет	Назначение
`@js-joda/core`	Основное API
`@js-joda/locale`	Локализация
`@js-joda/timezone`	Часовые пояса
`@js-joda/locale_ru`	Русская локаль
`@js-joda/locale_de`	Немецкая локаль

Поддерживаемые типы объектов

Локализованное форматирование поддерживают:

LocalDate
LocalTime
LocalDateTime
OffsetDateTime
ZonedDateTime
YearMonth
MonthDay

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

import { YearMonth } from '@js-joda/core';

const ym = YearMonth.of(2025, 3);

const formatter = DateTimeFormatter
    .ofPattern('LLLL yyyy')
    .withLocale(Locale.forLanguageTag('ru'));

console.log(ym.format(formatter));

Результат:

март 2025

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

import { MonthDay } from '@js-joda/core';

const md = MonthDay.of(3, 18);

const formatter = DateTimeFormatter
    .ofPattern('d MMMM')
    .withLocale(Locale.forLanguageTag('ru'));

console.log(md.format(formatter));

Результат:

18 марта