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

В Flatpickr система локализации построена вокруг объекта locale, который управляет не только языковыми строками интерфейса, но и правилами отображения дат, первым днем недели, форматом месяцев, дней и рядом поведенческих параметров календаря. Подход библиотеки заключается в разделении визуального формата (dateFormat, altFormat) и языкового слоя (locale), что позволяет независимо управлять представлением данных и их интерпретацией.

Базовая структура локали

Каждая локаль в Flatpickr представляет собой JavaScript-объект, содержащий набор полей:

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

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

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

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

Подключение готовых локалей

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

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

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

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

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

Формат даты и разделение ответственности

В Flatpickr существует два основных параметра форматирования:

  • dateFormat — формат значения, сохраняемого в input
  • altFormat — формат отображаемого значения (при использовании altInput)

Пример:

flatpickr("#input", {
  locale: Russian,
  dateFormat: "Y-m-d",
  altInput: true,
  altFormat: "d F Y"
});

В данном случае:

  • внутреннее значение: 2026-05-30
  • отображаемое значение: 30 Май 2026

Локаль влияет на текстовые части (F — месяц), а формат определяет структуру строки.

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

Flatpickr использует собственную систему токенов:

  • d — день месяца
  • m — месяц (число)
  • F — месяц (полное название)
  • M — сокращённый месяц
  • Y — год
  • H — часы (24-часовой формат)
  • h — часы (12-часовой формат)
  • i — минуты
  • S — секунды

При использовании локали изменяется не сам токен, а его текстовое представление. Например:

  • F в русской локали → «Май»
  • F в английской → «May»

Таким образом, формат остаётся универсальным, а локаль отвечает за словарь подстановки.

Первый день недели и региональные различия

Одним из ключевых параметров локали является firstDayOfWeek. Он определяет старт календарной сетки:

  • 0 — воскресенье
  • 1 — понедельник
  • 2 — вторник и т.д.

Пример для европейского формата:

{
  firstDayOfWeek: 1
}

Для США чаще используется:

{
  firstDayOfWeek: 0
}

Этот параметр влияет на разметку календаря, но не затрагивает формат строки даты.

RTL-языки и направление интерфейса

Некоторые локали требуют поддержки right-to-left отображения. Flatpickr не меняет направление документа автоматически, но предоставляет возможность интеграции через CSS и настройки окружения.

Пример настройки:

flatpickr("#input", {
  locale: Arabic
});

Дополнительно обычно требуется CSS:

.flatpickr-calendar {
  direction: rtl;
}

RTL-локали затрагивают расположение дней недели, стрелок навигации и порядка месяцев.

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

Flatpickr позволяет менять локаль во время выполнения через API:

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

fp.set("locale", Russian);

При смене локали пересобирается интерфейс календаря, включая:

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

При этом выбранная дата остается неизменной, так как хранится в объекте Date.

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

При использовании режима диапазона (mode: "range") локаль также влияет на разделитель:

{
  mode: "range",
  locale: {
    rangeSeparator: " до "
  }
}

Стандартный формат:

10 Май 2026 — 20 Май 2026

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

Пользовательские локали и расширение системы

Создание собственной локали требует соблюдения структуры, совместимой с внутренним L10n-механизмом Flatpickr:

const customLocale = {
  weekdays: {
    shorthand: ["A", "B", "C", "D", "E", "F", "G"],
    longhand: ["День1", "День2", "День3", "День4", "День5", "День6", "День7"]
  },
  months: {
    shorthand: ["M1", "M2", "M3", "M4", "M5", "M6", "M7", "M8", "M9", "M10", "M11", "M12"],
    longhand: ["Месяц1", "Месяц2", "Месяц3", "Месяц4", "Месяц5", "Месяц6",
               "Месяц7", "Месяц8", "Месяц9", "Месяц10", "Месяц11", "Месяц12"]
  },
  firstDayOfWeek: 1,
  rangeSeparator: " - "
};

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

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

Flatpickr допускает независимую комбинацию локали и формата:

flatpickr("#input", {
  locale: Russian,
  dateFormat: "d.m.Y",
  altInput: true,
  altFormat: "j F, Y"
});

В этом примере:

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

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

Особенности работы с 12/24-часовым временем

Хотя локаль не всегда напрямую управляет форматом времени, она часто используется совместно с параметром time_24hr:

flatpickr("#input", {
  enableTime: true,
  time_24hr: true,
  locale: Russian
});

В разных регионах предпочтения различаются:

  • Европа и Россия: 24-часовой формат
  • США: 12-часовой формат с AM/PM

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

Механика подстановки текстовых значений

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

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

При изменении локали происходит повторная генерация DOM-элементов календаря, что обеспечивает консистентность отображения без ручного обновления UI.

Поведение при частичном определении локали

Если локаль определена неполностью, Flatpickr использует fallback на английскую локаль. Это касается любых отсутствующих полей:

  • отсутствующие месяцы
  • отсутствующие дни недели
  • отсутствующие строки интерфейса

Такой механизм предотвращает поломку UI при некорректных или минимальных пользовательских локалях.

Итоговая модель взаимодействия компонентов локализации

Система локализации Flatpickr строится на трёх независимых уровнях:

  • Date object — хранение и вычисления
  • Format tokens — структура строки
  • Locale (L10n) — языковое представление и региональные правила

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

Оглавление