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

Модель локализации в js-joda

Библиотека js-joda изначально построена вокруг строгой модели ISO-8601 и не включает локализацию «из коробки» в ядре. Локали подключаются отдельно через дополнительные пакеты и используются преимущественно на уровне форматирования и парсинга строковых представлений дат и времени.

Основной принцип архитектуры локалей заключается в разделении:

  • ядро (core) — неизменяемые классы времени (LocalDate, LocalTime, ZonedDateTime и т.д.)
  • форматирование — DateTimeFormatter и связанные механизмы
  • локализация — внешние наборы данных, подключаемые по необходимости

Такой подход позволяет уменьшить размер ядра и не навязывать региональные настройки тем, кому они не нужны.

Установка и подключение локалей

Поддержка локалей реализуется через отдельные пакеты:

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

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

npm install @js-joda/locale_fr
npm install @js-joda/locale_de
npm install @js-joda/locale_ru

Каждый пакет локали содержит набор правил форматирования: названия месяцев, дней недели, форматы даты, правила отображения AM/PM и другие региональные особенности.

Подключение базовой локали

После установки необходимо импортировать как ядро, так и локальные данные:

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

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

Импорт пакета локали (@js-joda/locale_en) не возвращает значение, но регистрирует данные внутри системы js-joda.

Использование Locale при форматировании

Локаль применяется через объект DateTimeFormatter.

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

import { LocalDate } from '@js-joda/core';
import { DateTimeFormatter } from '@js-joda/core';
import { Locale } from '@js-joda/locale';
import '@js-joda/locale_en';

const date = LocalDate.of(2026, 5, 25);

const formatter = DateTimeFormatter
  .ofPattern('EEEE, d MMMM yyyy')
  .withLocale(Locale.US);

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

В этом примере локаль влияет на:

  • название дня недели (EEEE)
  • название месяца (MMMM)
  • порядок и правила отображения компонентов даты

Влияние локали на шаблоны форматирования

Один и тот же шаблон может давать разные результаты в зависимости от локали.

Пример различий

const formatter = DateTimeFormatter
  .ofPattern('d MMMM yyyy')
  .withLocale(Locale.US);
const formatterFR = DateTimeFormatter
  .ofPattern('d MMMM yyyy')
  .withLocale(Locale.FRANCE);

Результат:

  • US: May 25 2026
  • FR: 25 mai 2026

Разница определяется не шаблоном, а локализованными данными.

Поддерживаемые категории локализованных данных

Локали влияют на несколько уровней представления:

Названия календарных элементов

  • дни недели
  • месяцы
  • сокращённые формы (Jan, Feb, Mon, Tue)

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

  • порядок компонентов (день/месяц/год)
  • разделители
  • текстовые обозначения времени

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

  • AM / PM
  • 24-часовой или 12-часовой формат

Подключение нескольких локалей

В реальных приложениях часто подключается несколько языков одновременно.

import '@js-joda/locale_en';
import '@js-joda/locale_fr';
import '@js-joda/locale_de';

Выбор локали выполняется динамически:

function formatDate(date, locale) {
  return date.format(
    DateTimeFormatter
      .ofPattern('EEEE, d MMMM yyyy')
      .withLocale(locale)
  );
}

Работа с Locale объектом

Объект Locale является ключевым элементом управления локализацией.

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

const us = Locale.US;
const france = Locale.FRANCE;

Также возможно создание пользовательских локалей:

const custom = new Locale('ru', 'RU');

Однако полноценная поддержка зависит от того, загружены ли соответствующие данные локали.

Парсинг строк с учётом локали

Локаль влияет не только на форматирование, но и на обратную операцию — разбор строки.

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

const date = LocalDate.parse('25 May 2026', formatter);

Если локаль не соответствует входной строке, парсинг может завершиться ошибкой или неверным результатом.

Локали и строгая модель ISO

Важная особенность js-joda: локаль никогда не влияет на внутреннее представление даты.

const date = LocalDate.of(2026, 5, 25);

Эта дата всегда:

  • год: 2026
  • месяц: 5
  • день: 25

Локаль влияет только на строковое представление, но не изменяет структуру данных.

Смешивание локалей и часовых поясов

Локаль и временные зоны — независимые механизмы:

  • локаль отвечает за текстовое представление
  • временная зона — за абсолютное время
import { ZonedDateTime, ZoneId } from '@js-joda/core';
import { Locale } from '@js-joda/locale';

const zdt = ZonedDateTime.now(ZoneId.of('Europe/Paris'));

const formatter = DateTimeFormatter
  .ofPattern('EEEE, d MMMM yyyy HH:mm')
  .withLocale(Locale.FRANCE);

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

Поведение при отсутствии локализации

Если локаль не подключена или отсутствуют данные:

  • используются базовые ISO-значения
  • текстовые элементы могут быть англоязычными
  • некоторые паттерны остаются без локального преобразования

Это делает систему предсказуемой даже в минимальной конфигурации.

Совместимость с Intl и внешними форматерами

js-joda не заменяет Intl.DateTimeFormat, но может использоваться совместно.

Различия:

  • js-joda: строгая модель, воспроизводимость, неизменяемость
  • Intl: встроенная системная локализация браузера/Node.js

При необходимости js-joda применяется как источник данных, а Intl — как слой отображения.

Особенности локалей в шаблонах с текстовыми элементами

Шаблоны могут содержать буквенные сегменты:

DateTimeFormatter.ofPattern("'Дата:' d MMMM yyyy")

При использовании локали:

  • числа остаются неизменными
  • текстовые элементы форматируются через локаль
  • кавычки фиксируют неизменяемые строки

Поведение сокращённых и полных форм

Локаль определяет, какие формы используются:

  • MMM — сокращённый месяц
  • MMMM — полный месяц
  • EEE — короткий день недели
  • EEEE — полный день недели
const formatter = DateTimeFormatter
  .ofPattern('EEEE, MMMM d')
  .withLocale(Locale.US);

Ограничения системы локалей

Система локалей js-joda имеет ряд принципиальных ограничений:

  • не выполняет автоматическую смену локали по окружению
  • не включает все языки в core-пакет
  • требует явного подключения данных
  • не изменяет бизнес-логику времени

Эти ограничения являются частью архитектурной модели предсказуемости и минимализма.

Роль локалей в архитектуре форматирования

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

Ключевое свойство системы:

  • одна и та же дата остаётся неизменной
  • множество представлений зависит от локали
  • форматирование отделено от модели данных
Оглавление