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

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

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

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

Структура локалей в date-fns

Каждая локаль находится в отдельном пакете внутри date-fns/locale.

Примеры:

  • date-fns/locale/ru — русский язык
  • date-fns/locale/en-US — американский английский
  • date-fns/locale/de — немецкий язык

Каждая локаль экспортирует объект с набором правил:

{
  code: 'ru',
  formatDistance: { ... },
  formatLong: { ... },
  formatRelative: { ... },
  localize: { ... },
  match: { ... },
  options: { ... }
}

Этот объект используется всеми функциями форматирования внутри библиотеки.

Подключение локали в отдельных функциях

Наиболее распространённый способ — передача локали через опции функции.

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

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

const date = new Date(2026, 0, 24)

const result = format(date, 'EEEE, d MMMM yyyy', {
  locale: ru
})

console.log(result)

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

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

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

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

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

function formatByLocale(date, localeCode) {
  const locales = {
    ru,
    en: enUS,
    de
  }

  return format(date, 'PPPP', {
    locale: locales[localeCode]
  })
}

Такой подход позволяет централизовать выбор локали на уровне приложения.

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

date-fns поддерживает настройку опций по умолчанию через setDefaultOptions.

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

setDefaultOptions({
  locale: ru
})

const date = new Date(2026, 0, 24)

console.log(format(date, 'PPPP'))

После установки:

  • все функции используют указанную локаль по умолчанию
  • необходимость передавать locale в каждом вызове отпадает

Важно учитывать: глобальные настройки применяются в пределах текущего модуля, что критично при серверном рендеринге.

Локали и форматирование строк

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

  • относительные даты (formatRelative)
  • расстояния во времени (formatDistance)
  • длинные и короткие форматы дат (formatLong)

Пример относительных дат

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

const date = new Date()

const result = formatRelative(date, new Date(), {
  locale: ru
})

console.log(result)

Результат может быть вида: сегодня в 12:00

Импорт локалей и tree-shaking

date-fns спроектирована так, чтобы поддерживать tree-shaking.

Корректный импорт:

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

или

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

При использовании bundler’ов (Vite, Webpack, Rollup) важно:

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

Неправильный подход:

import * as locales from 'date-fns/locale'

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

Использование локалей в SSR (Server-Side Rendering)

При серверном рендеринге локаль должна быть определена на каждый запрос отдельно.

Типичный подход:

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

export function renderDate(date, lang) {
  const localeMap = {
    ru,
    en: enUS
  }

  return format(date, 'PPPP', {
    locale: localeMap[lang] || enUS
  })
}

Особенность:

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

Работа с форматами и локалью

Некоторые форматы зависят от локали напрямую.

Пример:

format(date, 'PPP', { locale: ru })
  • PPP — локализованный длинный формат даты
  • структура результата определяется локалью

Для разных языков результат одного и того же шаблона будет отличаться:

  • русский: 24 января 2026 г.
  • английский: January 24th, 2026

Распространённые ошибки при подключении локалей

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

format(date, 'PPPP')

Результат будет в английской локали по умолчанию.

2. Неправильный импорт

import { ru } from 'date-fns'

Такой импорт некорректен, локаль не будет подключена.

3. Подключение всех локалей

import * as locales from 'date-fns/locale'

Приводит к увеличению размера бандла и потере tree-shaking.

4. Конфликт глобальной и локальной локали

setDefaultOptions({ locale: ru })

format(date, 'PPPP', { locale: enUS })

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

Архитектурные особенности локалей date-fns

Система локалей построена на нескольких уровнях:

  • localize — перевод единиц времени
  • formatDistance — расстояния между датами
  • formatRelative — относительные выражения
  • formatLong — длинные форматы дат
  • match — парсинг строк в даты

Такой подход делает локализацию не просто переводом строк, а полноценной языковой моделью форматирования дат.

Принципы эффективного использования локалей

  • подключается только необходимый набор языков
  • локаль передаётся явно в критичных участках кода
  • глобальная локаль используется только в однопользовательских или изолированных приложениях
  • SSR всегда требует контекстной локали
  • импорт локалей должен быть статическим для корректного tree-shaking
Оглавление