Опции локализации

Библиотека Luxon предоставляет мощную систему локализации, которая влияет на форматирование дат, времени, относительных значений и календарных представлений. В основе лежит использование стандартов ICU (International Components for Unicode) и встроенных возможностей JavaScript для работы с локалями.

Локализация в Luxon определяется двумя ключевыми аспектами:

  • локаль (locale) — язык и регион форматирования;
  • параметры форматирования — правила отображения даты, времени, чисел и относительных выражений.

Установка локали

Локаль задаёт основной язык форматирования. В Luxon она передаётся строкой в формате BCP 47 (например, en, ru, ru-KZ, fr, de).

Установка локали для отдельного объекта

Каждый объект DateTime хранит собственную локаль:

import { DateTime } from "luxon";

const dt = DateTime.now().setLocale("ru");

Локаль не изменяет глобальное состояние, а применяется только к конкретному экземпляру.

Глобальная локаль через Settings

Luxon позволяет задать локаль по умолчанию для всех создаваемых объектов:

import { Settings } from "luxon";

Settings.defaultLocale = "ru";

После этого все новые DateTime будут использовать указанную локаль, если не переопределено локально.

Форматы локализованного вывода

Luxon поддерживает несколько предустановленных форматов, которые автоматически адаптируются под выбранную локаль.

Основные форматы

  • DATE_SHORT
  • DATE_MED
  • DATE_LONG
  • DATE_HUGE
  • TIME_SIMPLE
  • TIME_WITH_SECONDS
  • DATETIME_SHORT
  • DATETIME_MED
  • DATETIME_LONG
  • DATETIME_HUGE

Пример:

const dt = DateTime.now().setLocale("ru");

dt.toLocaleString(DateTime.DATE_MED);

Вывод зависит от локали. Например:

  • ru: 23 мая 2026 г.
  • en: May 23, 2026

Настройка формата через toLocaleString

Метод toLocaleString — основной инструмент локализованного форматирования.

DateTime.now().setLocale("ru").toLocaleString({
  weekday: "long",
  year: "numeric",
  month: "long",
  day: "2-digit"
});

Результат:

суббота, 23 мая 2026

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

Luxon использует конфигурацию, аналогичную Intl.DateTimeFormat:

  • weekday
  • year
  • month
  • day
  • hour
  • minute
  • second
  • hour12

Значения параметров:

  • "numeric"
  • "2-digit"
  • "long"
  • "short"
  • "narrow"

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

Форматирование времени также зависит от локали.

DateTime.now()
  .setLocale("en")
  .toLocaleString(DateTime.TIME_WITH_SECONDS);

Пример вывода:

3:45:12 PM

В русской локали:

15:45:12

Разница обусловлена использованием 12-часового или 24-часового формата, который определяется региональными настройками.

Форматирование даты и времени через preset-константы

Luxon предоставляет удобные предустановленные наборы форматов:

DateTime.now().setLocale("ru").toLocaleString(DateTime.DATETIME_MED);

Пример вывода:

23 мая 2026 г., 15:45

Эти пресеты автоматически комбинируют локализованные правила даты и времени.

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

При смене локали автоматически изменяются:

  • названия месяцев
  • названия дней недели
  • сокращённые формы

Пример:

DateTime.now().setLocale("fr").toLocaleString({
  weekday: "long",
  month: "long",
  day: "numeric"
});

Результат:

samedi, 23 mai

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

Локаль может включать регион:

  • en-US
  • en-GB
  • ru-RU
  • ru-KZ

Регион влияет на:

  • порядок элементов даты;
  • разделители;
  • формат времени (12/24 часа);
  • отображение числовых значений.

Пример:

DateTime.now().setLocale("en-GB").toLocaleString();

Пример вывода:

23/05/2026

В то время как en-US даст:

5/23/2026

Локализация относительных дат

Luxon поддерживает вывод относительных выражений через toRelative() и toRelativeCalendar().

Относительное время

DateTime.now()
  .minus({ hours: 3 })
  .setLocale("ru")
  .toRelative();

Результат:

3 часа назад

В английской локали:

3 hours ago

Календарные выражения

DateTime.now()
  .plus({ days: 2 })
  .setLocale("ru")
  .toRelativeCalendar();

Результат:

через 2 дня

Пользовательские локали и кастомизация

Luxon опирается на ICU-локали, поэтому глубокая кастомизация ограничена, но возможна через:

  • изменение формата вывода;
  • переопределение локали через setLocale;
  • использование Intl.DateTimeFormat через .toFormat() косвенно.

Пример кастомного формата:

DateTime.now().setLocale("ru").toFormat("cccc dd LLLL yyyy");

Вывод:

суббота 23 мая 2026

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

Метод toFormat не полностью зависит от локали, но использует её для текстовых элементов:

DateTime.now()
  .setLocale("ru")
  .toFormat("dd MMMM yyyy, cccc");

Результат:

23 мая 2026, суббота

Влияние локали на парсинг строк

При разборе дат через fromFormat локаль критически важна, если используются текстовые месяцы или дни недели.

DateTime.fromFormat(
  "23 мая 2026",
  "dd LLLL yyyy",
  { locale: "ru" }
);

Без указания локали парсинг может быть некорректным, так как LLLL зависит от языка.

Наследование локали при преобразованиях

Все производные объекты сохраняют локаль исходного DateTime:

const dt = DateTime.now().setLocale("ru");

const shifted = dt.plus({ days: 5 });

shifted.toLocaleString(DateTime.DATE_FULL);

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

Совместимость с Intl API

Luxon использует Intl.DateTimeFormat под капотом, поэтому:

  • поведение локалей соответствует стандартам ECMAScript;
  • поддержка локалей зависит от среды выполнения (Node.js / браузер);
  • возможны различия в редких региональных форматах.

Ограничения локализации

Несмотря на гибкость, существуют ограничения:

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

Приоритет локалей

Luxon применяет локаль по следующему приоритету:

  1. Локаль конкретного объекта (setLocale);
  2. Глобальная локаль (Settings.defaultLocale);
  3. Системная локаль среды выполнения;
  4. en как резервная локаль.
Оглавление