Настройка локализации

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

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

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

Такой подход делает поведение библиотеки предсказуемым и удобным для tree-shaking в сборщиках.

Структура локали

Каждая локаль в date-fns представляет собой JavaScript-объект с фиксированной структурой:

  • code — строковый идентификатор языка и региона
  • formatDistance — правила для выражений типа «2 минуты назад»
  • formatLong — шаблоны длинных форматов дат
  • formatRelative — правила для относительных дат (вчера, сегодня, завтра)
  • localize — локализация месяцев, дней недели и порядковых чисел
  • match — парсинг строковых представлений дат

Примерно это выглядит как набор функций и словарей, объединённых в один объект, который затем используется внутри форматирующих функций.

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

Локали в date-fns поставляются как отдельные модули. Это важно для уменьшения размера бандла и контроля над импортируемыми данными.

Импорт выполняется напрямую из пакета локалей:

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

или более точечно:

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

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

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

Основной механизм локализации проявляется в функции format. Локаль передаётся через объект опций.

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

format(new Date(2026, 0, 24), 'EEEE, d MMMM yyyy', {
  locale: ru
})

Форматирование строк учитывает:

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

Без передачи локали используется локаль по умолчанию (обычно английская).

Установка локали по умолчанию

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

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

setDefaultOptions({ locale: ru })

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

Механизм основан на внутреннем контексте библиотеки и применяется ко всем операциям, поддерживающим опции.

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

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

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

formatDistance(new Date(2026, 0, 20), new Date(2026, 0, 24), {
  locale: ru,
  addSuffix: true
})

Локаль определяет:

  • форму слова «минута», «час», «день»
  • правила склонения числительных
  • суффиксы вроде «назад» или «через»

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

Относительное форматирование дат

Функция formatRelative формирует выражения вроде «вчера в 14:00» или «завтра в 10:00».

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

formatRelative(new Date(2026, 0, 25, 10, 0), new Date(2026, 0, 24), {
  locale: ru
})

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

  • сегодня
  • вчера
  • завтра
  • другие даты

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

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

Компонент localize внутри локали отвечает за преобразование числовых значений в текстовые представления.

Он содержит:

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

Пример использования происходит не напрямую, а через форматирующие токены:

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

format(new Date(2026, 4, 15), 'd MMMM', { locale: ru })

Результат зависит от локализованных массивов внутри объекта ru.

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

Форматные токены в date-fns интерпретируются с учётом локали. Особенно это касается:

  • MMMM — полное название месяца
  • MMM — сокращённое название месяца
  • EEEE — день недели
  • aa / aaa — периоды суток

Каждая локаль определяет собственные словари, которые подставляются при обработке токенов.

Механизм подключения локалей и tree-shaking

Локали реализованы как независимые модули, что позволяет сборщикам (Webpack, Vite, Rollup) удалять неиспользуемые языки из итогового бандла.

Импорт конкретной локали:

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

или:

import fr from 'date-fns/locale/fr'

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

Совместимость локалей с функциями date-fns

Поддержка локалей присутствует в большинстве функций:

  • format
  • formatDistance
  • formatRelative
  • formatDistanceToNow
  • formatDuration (в некоторых версиях через дополнительные пакеты)

Передача осуществляется через объект опций:

{
  locale: <localeObject>
}

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

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

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

Структура должна включать:

  • formatDistance
  • formatLong
  • formatRelative
  • localize
  • match

Примерно это выглядит как реализация аналогичного объекта с собственными правилами грамматики и форматирования.

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

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

format(new Date(), "EEEE, d MMMM yyyy 'в' HH:mm", { locale })

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

Таким образом достигается смешивание локализованных и фиксированных частей строки.

Особенности работы с разными регионами

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

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

Например, различия между en-US и en-GB отражаются в formatLong и formatRelative.

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

При отсутствии параметра locale применяется базовая английская локализация. Это влияет на:

  • названия месяцев
  • дни недели
  • форматы относительного времени

Внутренне используется дефолтный объект, встроенный в библиотеку, без необходимости дополнительных импортов.

Интеграция локалей в прикладные сценарии

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

  • списки событий
  • ленты активности
  • календарные компоненты
  • уведомления и логирование

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

Оглавление