Перевод названий месяцев и дней недели

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

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

Структура локалей и принцип подключения

Каждая локаль в date-fns — это объект, содержащий:

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

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

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

После подключения локаль передаётся в опции функций форматирования:

format(new Date(2026, 0, 1), 'PPPP', { locale: ru });

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

Перевод названий месяцев

Названия месяцев в date-fns хранятся в локали в нескольких форматах:

  • полные названия (long)
  • сокращённые формы (abbreviated)
  • генитивные формы (в некоторых языках)

В русской локали используются формы:

Месяц Полное название
Январь январь
Февраль февраль
Март март
Апрель апрель
Май май
Июнь июнь
Июль июль
Август август
Сентябрь сентябрь
Октябрь октябрь
Ноябрь ноябрь
Декабрь декабрь

При форматировании через format библиотека автоматически подставляет нужное значение в зависимости от токена:

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

Пример использования:

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

const date = new Date(2026, 4, 22);

format(date, 'MMMM', { locale: ru });
// "май"

Сокращённый вариант:

format(date, 'MMM', { locale: ru });
// "май" (для русского часто совпадает с полной формой)

Перевод дней недели

Дни недели в date-fns также представлены в локали в виде массива значений.

В русской локали порядок следующий:

  • воскресенье
  • понедельник
  • вторник
  • среда
  • четверг
  • пятница
  • суббота

Полные формы:

День Название
Sunday воскресенье
Monday понедельник
Tuesday вторник
Wednesday среда
Thursday четверг
Friday пятница
Saturday суббота

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

  • EEEE — полное название дня недели
  • EEE — сокращённое

Пример:

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

Сокращённая форма:

format(new Date(2026, 4, 22), 'EEE', { locale: ru });
// "пт"

Механизм работы format и выбор локализованных строк

Функция format внутри date-fns не содержит встроенных языковых строк. Она работает по следующему принципу:

  1. Разбирается шаблон формата ('PPPP', 'EEEE', 'MMMM')
  2. Определяется тип токена (месяц, день недели и т.д.)
  3. Вызывается соответствующий обработчик локали
  4. Из локального объекта извлекается нужная строка

Упрощённо можно представить логику так:

locale.months.formatting.long[monthIndex]
locale.weekdays.formatting.long[dayIndex]

Таким образом, перевод не «вшит» в функцию форматирования, а полностью делегирован объекту локали.

Форматы месяцев и дней в разных контекстах

Локали date-fns различают контексты использования слов:

  • standalone — самостоятельное использование (например, список месяцев)
  • formatting — использование внутри даты

В некоторых языках (например, немецком или французском) это различие критично, поскольку формы слов меняются в зависимости от грамматики.

Пример структуры:

months: {
  format: {
    wide: [...],
    abbreviated: [...]
  },
  standalone: {
    wide: [...],
    abbreviated: [...]
  }
}

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

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

Хотя основная задача локализации — перевод, важным элементом остаётся настройка календарной логики.

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

  • первый день недели — понедельник

Это влияет на функции:

  • startOfWeek
  • getWeek
  • формат календарных сеток

Пример:

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

startOfWeek(new Date(2026, 4, 22), { locale: ru });

Использование локали в разных функциях

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

  • formatDistance — «5 минут назад»
  • formatRelative — «вчера в 14:00»
  • formatDistanceToNow

Пример:

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

formatDistance(new Date(2026, 4, 23), new Date(2026, 4, 22), {
  locale: ru
});
// "1 день"

В этих функциях локаль определяет не только слова, но и грамматические формы чисел.

Кастомизация локалей

date-fns позволяет создавать собственные локали или модифицировать существующие.

Структура минимальной локали:

const customLocale = {
  code: 'custom',
  formatDistance: () => {},
  formatLong: {},
  formatRelative: () => {},
  localize: {
    month: (n) => ['Янв', 'Фев', 'Мар'][n],
    day: (n) => ['Вс', 'Пн', 'Вт'][n]
  },
  options: {
    weekStartsOn: 1
  }
};

Такой подход используется при:

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

Токены форматирования и влияние локали

Основные токены, связанные с переводом:

  • MMMM — месяц (полный)
  • MMM — месяц (сокращённый)
  • EEEE — день недели (полный)
  • EEE — день недели (сокращённый)
  • i — ISO-день недели (в некоторых контекстах локализуется)

Пример комбинированного форматирования:

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

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

Русский язык в date-fns имеет ряд характерных особенностей:

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

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

Влияние локали на производительность и сборку

При использовании tree-shaking в современных сборщиках:

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

Пример оптимального импорта:

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

Избыточный импорт всех локалей:

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

также возможен, но увеличивает размер итоговой сборки.

Итоговая модель работы перевода

Система перевода месяцев и дней недели в date-fns строится на трёх уровнях:

  • шаблоны форматирования (format)
  • языковые пакеты (locale objects)
  • токены, определяющие тип отображаемого значения

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

Оглавление