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

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

Механизм локализации основан на JavaScript-объекте, содержащем строки интерфейса и настройки календаря. Каждая локаль представляет собой самостоятельный модуль, экспортирующий объект с предопределёнными полями:

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

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

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

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

Подключение через npm

При установке через npm локаль импортируется отдельно:

import { Russian } from "flatpickr/dist/l10n/ru.js";
import flatpickr from "flatpickr";

После импорта объект локализации передаётся в конфигурацию:

flatpickr("#date", {
  locale: Russian
});

Подключение через CDN

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

<script src="https://cdn.jsdelivr.net/npm/flatpickr"></script>
<script src="https://cdn.jsdelivr.net/npm/flatpickr/dist/l10n/ru.js"></script>

Далее локаль доступна глобально:

flatpickr("#date", {
  locale: flatpickr.l10ns.ru
});

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

Flatpickr позволяет установить глобальную локализацию, которая будет применяться ко всем экземплярам календаря без необходимости повторного указания.

import flatpickr from "flatpickr";
import { Russian } from "flatpickr/dist/l10n/ru.js";

flatpickr.localize(Russian);

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

Структура объекта локализации

Объект ru содержит набор ключей, определяющих поведение интерфейса:

  • firstDayOfWeek — индекс первого дня недели
  • weekdays — массив названий дней недели
  • months — массив названий месяцев
  • ordinal — функция формирования порядковых числительных
  • rangeSeparator — разделитель диапазона дат

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

const Russian = {
  weekdays: {
    shorthand: ["Вс", "Пн", "Вт", "Ср", "Чт", "Пт", "Сб"],
    longhand: ["Воскресенье", "Понедельник", "Вторник", "Среда", "Четверг", "Пятница", "Суббота"]
  },
  months: {
    shorthand: ["Янв", "Фев", "Мар", "Апр", "Май", "Июн", "Июл", "Авг", "Сен", "Окт", "Ноя", "Дек"],
    longhand: ["Январь", "Февраль", "Март", "Апрель", "Май", "Июнь", "Июль", "Август", "Сентябрь", "Октябрь", "Ноябрь", "Декабрь"]
  },
  firstDayOfWeek: 1,
  rangeSeparator: " — "
};

Форматирование дат и региональные особенности

Локализация влияет не только на текст интерфейса, но и на восприятие даты пользователем. В русской локали принято использовать порядок день-месяц-год, что задаётся через параметр dateFormat.

flatpickr("#date", {
  locale: Russian,
  dateFormat: "d.m.Y"
});

Основные токены форматирования:

  • d — день месяца (01–31)
  • m — месяц (01–12)
  • Y — полный год
  • H — часы (24-часовой формат)
  • i — минуты

При включении временного выбора локализация также влияет на отображение AM/PM, если оно используется, хотя в русской локали чаще применяется 24-часовой формат.

Начало недели и календарная сетка

Важным параметром локализации является firstDayOfWeek, определяющий первый день недели.

Для русской локали стандартное значение:

firstDayOfWeek: 1

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

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

Переопределение локали

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

import { Russian } from "flatpickr/dist/l10n/ru.js";

const customRussian = {
  ...Russian,
  rangeSeparator: " до "
};

flatpickr("#date", {
  locale: customRussian
});

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

Динамическое переключение языка

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

Пример пересоздания:

let fp = flatpickr("#date", {
  locale: Russian
});

fp.destroy();

fp = flatpickr("#date", {
  locale: English
});

Альтернативный способ — глобальное изменение локали:

flatpickr.localize(English);

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

Влияние локализации на плагины

Некоторые плагины Flatpickr зависят от локализации, особенно:

  • range selection
  • time picker
  • week numbers

Например, при включении диапазона дат (mode: "range") используется rangeSeparator, определённый в локали:

flatpickr("#range", {
  mode: "range",
  locale: Russian
});

Это влияет на отображение выбранного диапазона в инпуте.

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

Локализация также влияет на парсинг пользовательского ввода. Flatpickr пытается интерпретировать дату в соответствии с заданным форматом и локалью. В русской локали это особенно важно, так как различие между mm/dd/yyyy и dd.mm.yyyy может приводить к ошибкам интерпретации.

При неправильном формате пользовательский ввод может не распознаваться:

flatpickr("#date", {
  locale: Russian,
  dateFormat: "d.m.Y",
  allowInput: true
});

Параметр allowInput усиливает гибкость ввода, но требует строгого соответствия формату.

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

На практике встречаются несколько типичных ошибок:

1. Неправильный импорт локали Использование неверного пути приводит к отсутствию перевода и возврату к английскому интерфейсу.

2. Конфликт глобальной и локальной локализации Если flatpickr.localize() установлен глобально, а в экземпляре передана другая локаль, может возникнуть несоответствие интерфейса.

3. Игнорирование dateFormat Даже при правильной локализации формат даты остаётся англоязычным, если явно не указан.

4. Несовместимость с кастомными плагинами Некоторые сторонние расширения не учитывают l10n и требуют ручной адаптации строк.

Расширение локализации под бизнес-логику

В сложных приложениях локализация используется не только для перевода интерфейса, но и как слой бизнес-настроек:

  • изменение разделителей диапазонов под CRM-форматы
  • адаптация названий месяцев под сокращённые внутренние коды
  • кастомизация подсказок под корпоративный стиль
const enterpriseLocale = {
  ...Russian,
  rangeSeparator: " → ",
  firstDayOfWeek: 1
};

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

Оглавление