Локализация форматов

js-joda ориентирована на строгую работу с датой и временем без неоднозначностей, характерных для встроенного Date. Локализация в этой библиотеке строится не вокруг неявного форматирования, а через явные правила преобразования временных объектов в строки с учётом языка, региона и принятых стандартов отображения.

Локализация в js-joda разделяется на два независимых слоя:

  • форматирование (DateTimeFormatter)
  • локаль (Locale)
  • стили отображения (TextStyle)
  • шаблоны (pattern-based formatting)

Такое разделение позволяет формировать представление даты без привязки к глобальным настройкам окружения, исключая побочные эффекты.

Локаль как параметр форматирования

Локаль определяет языковые правила отображения:

  • названия месяцев
  • названия дней недели
  • порядок элементов даты
  • формат времени (12/24 часа)
  • правила сокращений

В js-joda локаль передаётся явно через объект Locale.

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

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

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

const result = date.format(formatter);

В этом примере формат строки остаётся одинаковым, но текстовые элементы адаптируются под язык.

DateTimeFormatter как центр локализации

Основной механизм локализации реализуется через js-joda. Этот компонент отвечает за преобразование временных объектов в строковое представление.

Ключевые особенности:

  • неизменяемость (immutable)
  • композиция из паттерна и локали
  • явная настройка формата
  • поддержка стандартных и пользовательских шаблонов

Простейшее форматирование:

const formatter = DateTimeFormatter.ofPattern('yyyy-MM-dd');
date.format(formatter);

Добавление локали:

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

Символы шаблонов и их локализация

Паттерны используют специальные символы:

  • y — год
  • M — месяц
  • d — день месяца
  • E — день недели
  • H — часы (24h)
  • h — часы (12h)
  • m — минуты
  • s — секунды

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

  • MMMM → полное название месяца
  • MMM → сокращённое название месяца
  • EEEE → полное название дня недели
  • EEE → сокращённое название дня недели

Пример:

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

date.format(formatter);

Текстовые стили отображения

Вместо ручного задания шаблонов часто используются стили:

  • FULL
  • LONG
  • MEDIUM
  • SHORT

Они задают уровень детализации представления даты.

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

const formatter = DateTimeFormatter
  .ofLocalizedDate(FormatStyle.FULL)
  .withLocale(Locale.ITALIAN);

Стили управляют тем, как будет отображаться дата:

  • FULL — максимально подробный формат
  • SHORT — компактный формат
  • MEDIUM — баланс между читаемостью и краткостью
  • LONG — расширенное текстовое представление

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

Объекты даты и времени форматируются одинаковым механизмом:

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

const dt = LocalDateTime.of(2026, 5, 25, 18, 30);

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

dt.format(formatter);

Локаль влияет только на текстовые элементы, тогда как числовые части остаются стабильными.

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

js-joda предоставляет фабричные методы:

  • ofLocalizedDate
  • ofLocalizedTime
  • ofLocalizedDateTime

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

DateTimeFormatter.ofLocalizedDateTime(FormatStyle.MEDIUM)
  .withLocale(Locale.CHINESE);

Формат выбирается автоматически на основе локали и стиля.

Различие между паттерном и локализованным форматированием

Паттерн:

  • полностью управляется разработчиком
  • одинаковый для всех локалей
  • требует ручной настройки

Локализованный формат:

  • зависит от Locale
  • адаптируется к региональным стандартам
  • использует предопределённые правила

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

DateTimeFormatter.ofPattern('dd/MM/yyyy');
DateTimeFormatter.ofLocalizedDate(FormatStyle.SHORT);

Первый вариант фиксирован, второй — адаптивен.

Поддержка языков и расширения локалей

Базовая библиотека опирается на ICU-подобную модель локалей. Подключаемые расширения позволяют расширить список поддерживаемых языков и правил форматирования.

Локали могут влиять на:

  • порядок компонентов даты
  • разделители (точка, слэш, дефис)
  • написание месяцев
  • грамматические формы

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

  • en-US: 05/25/2026
  • de-DE: 25.05.2026
  • ja-JP: 2026/05/25

Форматирование времени с учётом локали

Временные значения также подчиняются локализации:

const timeFormatter = DateTimeFormatter
  .ofLocalizedTime(FormatStyle.SHORT)
  .withLocale(Locale.US);

В зависимости от локали:

  • используется 12-часовой или 24-часовой формат
  • добавляются AM/PM маркеры
  • изменяется порядок компонентов

Пользовательские шаблоны и локаль

Комбинация пользовательского паттерна и локали даёт гибридное поведение:

const formatter = DateTimeFormatter
  .ofPattern('d MMM yyyy, HH:mm')
  .withLocale(Locale.ITALIAN);

Здесь структура фиксирована, но текстовые элементы локализуются.

Локализация дней недели и месяцев

При использовании E и M происходит автоматическая подстановка текстовых значений:

  • день недели зависит от локали календаря
  • месяц формируется из языкового словаря
  • форма может быть сокращённой или полной
const formatter = DateTimeFormatter.ofPattern('EEEE MMMM')
  .withLocale(Locale.PORTUGUESE);

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

Форматтеры в js-joda неизменяемы. Каждое добавление локали создаёт новый экземпляр:

  • исходный formatter не изменяется
  • результат withLocale — новый объект
  • цепочки можно комбинировать
const base = DateTimeFormatter.ofPattern('d MMM yyyy');

const localized = base.withLocale(Locale.KOREAN);
const another = base.withLocale(Locale.SPANISH);

Совместимость локализации с временными зонами

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

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

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

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

Здесь локаль отвечает за язык, а зона — за смещение и отображение z.

Стратегия применения локализации

Локализация в js-joda строится на принципе явного контроля:

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

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

Оглавление