Русская локализация

date-fns реализует локализацию через набор предустановленных объектов локалей, каждый из которых содержит правила форматирования дат, склонения, месяцы, дни недели и правила построения относительных выражений времени.

Русская локализация представлена модулем ru, который включает:

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

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

Локаль импортируется отдельно от основного функционала библиотеки:

import { format } from 'date-fns'
import { ru } from 'date-fns/locale'

Использование локали происходит через опцию locale в функциях форматирования:

format(new Date(2026, 0, 24), 'd MMMM yyyy', { locale: ru })
// 24 января 2026

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

Форматирование дат с русской локализацией

Русская локаль влияет на поведение токенов date-fns, особенно тех, которые связаны с текстовыми представлениями дат.

Месяцы и дни недели

format(new Date(2026, 4, 22), 'EEEE', { locale: ru })
// пятница

format(new Date(2026, 4, 22), 'MMMM', { locale: ru })
// май

Важная особенность: в русском языке названия месяцев в формате по умолчанию возвращаются в именительном или родительном падеже в зависимости от контекста формата.

format(new Date(2026, 0, 1), 'd MMMM', { locale: ru })
// 1 января

Склонение числительных и грамматика

Русская локализация учитывает сложные правила склонения:

  • 1 день → «1 день»
  • 2 дня → «2 дня»
  • 5 дней → «5 дней»

Эти правила используются в функциях:

  • formatDistance
  • formatDistanceStrict

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

Функция formatDistance формирует человекочитаемые выражения времени:

import { formatDistance } from 'date-fns'
import { ru } from 'date-fns/locale'

formatDistance(new Date(2026, 4, 22), new Date(2026, 4, 20), { locale: ru })
// "2 дня назад"

При изменении направления вычисления:

formatDistance(new Date(2026, 4, 20), new Date(2026, 4, 22), { locale: ru })
// "через 2 дня"

Строгое форматирование

import { formatDistanceStrict } from 'date-fns'

formatDistanceStrict(new Date(2026, 4, 22), new Date(2026, 4, 20), { locale: ru })
// "2 дня"

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

Функция formatRelative позволяет выводить даты относительно текущего дня.

import { formatRelative } from 'date-fns'

formatRelative(new Date(2026, 4, 22), new Date(2026, 4, 21), { locale: ru })
// "сегодня в 00:00"

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

Разбор строк дат (parse) с локалью

При использовании parse локаль влияет на разбор текстовых представлений:

import { parse } from 'date-fns'

parse('24 января 2026', 'd MMMM yyyy', new Date(), { locale: ru })

Здесь критично совпадение:

  • формата строки;
  • падежей месяцев;
  • языка локали.

Несовпадение локали приводит к невозможности корректного разбора строки.

Глобальная установка локали

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

import { setDefaultOptions } from 'date-fns'
import { ru } from 'date-fns/locale'

setDefaultOptions({ locale: ru })

После этого все функции используют русскую локаль по умолчанию:

format(new Date(2026, 4, 22), 'd MMMM yyyy')
// 22 мая 2026

Особенность механизма:

  • применяется только к функциям date-fns;
  • не влияет на встроенный Intl.DateTimeFormat.

Особенности русской локализации

1. Падежная зависимость месяцев

В зависимости от шаблона форматирования месяц может менять форму:

  • «январь» (именительный)
  • «января» (родительный)

Это определяется контекстом токена MMMM и окружающих символов формата.

2. Сложные правила множественного числа

Внутри локали реализованы правила:

  • 1, 21, 31 → «день»
  • 2–4, 22–24 → «дня»
  • остальные → «дней»

Эти правила применяются автоматически в функциях расстояния.

3. Часовые форматы

Русская локаль поддерживает как 24-часовой, так и 12-часовой формат, но по умолчанию ориентирована на 24-часовую систему:

format(new Date(), 'HH:mm', { locale: ru })

Совместное использование с другими форматами

Локаль применяется независимо от сложности шаблона:

format(new Date(2026, 4, 22, 18, 45), 'EEEE, d MMMM yyyy, HH:mm', { locale: ru })
// пятница, 22 мая 2026, 18:45

Tree-shaking и размер локалей

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

import { ru } from 'date-fns/locale'

Неиспользование локали в коде приводит к её исключению при оптимизации сборки.

Ограничения и взаимодействие с временными зонами

Локаль не управляет временными зонами. Она отвечает только за:

  • язык;
  • грамматику;
  • форматирование.

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

  • date-fns-tz

Это разделение принципиально: локаль не изменяет фактическое значение времени, только его представление.

Частые ошибки при использовании локали

Отсутствие передачи locale

format(date, 'd MMMM')
// вывод на английском при дефолтной локали

Неправильный формат месяца

parse('24 май 2026', 'd MMMM yyyy', new Date(), { locale: ru })
// ошибка из-за падежа или формы

Ожидание глобальной локализации

Без setDefaultOptions библиотека не изменяет поведение автоматически.

Поведение токенов в русской локали

Ключевые токены и их влияние:

  • MMMM — полное название месяца с падежной адаптацией
  • MMM — сокращённое название месяца
  • EEEE — полное название дня недели
  • eee — сокращённое название дня недели
  • do — порядковое числительное с суффиксом
format(new Date(2026, 4, 22), 'do MMMM', { locale: ru })
// 22-е мая
Оглавление