Принципы работы локализации

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

Архитектура системы локализации

Основой локализации в Flatpickr является объект конфигурации locale. Он содержит набор свойств, определяющих:

  • названия дней недели;
  • названия месяцев;
  • форматы отображения времени;
  • текстовые подписи управляющих элементов;
  • правила порядковости дат и форматов.

Каждая локаль представляет собой независимый JavaScript-объект, который подмешивается в глобальные настройки или передаётся в конкретный экземпляр календаря.

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

При этом строковое значение "ru" является лишь идентификатором, который сопоставляется с заранее загруженным объектом локализации.

Разделение формата данных и отображения

Ключевой принцип локализации Flatpickr заключается в строгом отделении:

  • внутреннего формата хранения даты (ISO-подобные структуры и объекты Date);
  • визуального представления даты в интерфейсе.

Это означает, что локализация не влияет на вычисления, сравнение дат или их сортировку. Она отвечает исключительно за отображение и ввод.

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

  • порядок день/месяц/год;
  • использование 12- или 24-часового времени;
  • различия в разделителях.

Структура объекта locale

Типовой объект локализации включает несколько категорий данных.

Названия дней недели

weekdays: {
  shorthand: ["Вс", "Пн", "Вт", "Ср", "Чт", "Пт", "Сб"],
  longhand: ["Воскресенье", "Понедельник", "Вторник", "Среда", "Четверг", "Пятница", "Суббота"]
}

Используются два варианта:

  • shorthand — сокращённые формы для компактных интерфейсов;
  • longhand — полные названия для расширенного отображения.

Названия месяцев

months: {
  shorthand: ["Янв", "Фев", "Мар", "Апр", "Май", "Июн", "Июл", "Авг", "Сен", "Окт", "Ноя", "Дек"],
  longhand: ["Январь", "Февраль", "Март", "Апрель", "Май", "Июнь", "Июль", "Август", "Сентябрь", "Октябрь", "Ноябрь", "Декабрь"]
}

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

Локализация форматов дат

Flatpickr использует форматирование через собственную систему токенов, но локализация влияет на интерпретацию некоторых элементов:

  • порядок компонентов даты;
  • разделители;
  • отображение времени.

Пример формата:

dateFormat: "d.m.Y"

В разных локалях этот формат может быть переопределён на:

  • "m/d/Y" для англоязычных регионов;
  • "d/m/Y" для европейских локалей;
  • "Y-m-d" для ISO-ориентированных систем.

Важно, что сам парсер не зависит от локали напрямую — он опирается на формат строки, а локализация лишь задаёт дефолтные значения.

Локализация времени

При включении режима времени (enableTime) локализация начинает управлять дополнительными аспектами:

  • формат отображения часов;
  • разделители между часами и минутами;
  • подписи AM/PM (при 12-часовом формате).
time_24hr: true

При time_24hr: false локаль может предоставлять строки:

amPM: ["AM", "PM"]

или их эквиваленты для других языков.

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

Flatpickr не включает все локали в ядро по умолчанию. Они подключаются отдельно:

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

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

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

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

Механизм наследования локалей

Flatpickr поддерживает принцип переопределения локали на нескольких уровнях:

  1. глобальная локаль;
  2. локаль конкретного экземпляра;
  3. локаль, переданная через API вызов.

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

flatpickr.localize(Russian);

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

Обработка пользовательского ввода

Локализация влияет не только на отображение, но и на UX-уровень обработки ввода:

  • подсказки формата даты адаптируются под регион;
  • корректируется поведение автодополнения;
  • учитываются разделители, характерные для языка.

Однако сам процесс парсинга остаётся независимым от языка. Это предотвращает ошибки, связанные с неоднозначными датами вида 01/02/2026.

Форматы и токены локализации

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

  • d — день;
  • m — месяц;
  • Y — год;
  • H — часы;
  • i — минуты.

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

Особенности региональных различий

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

Порядок дат

Некоторые регионы используют нестандартные последовательности:

  • США: месяц-день-год;
  • Европа: день-месяц-год;
  • международный стандарт: год-месяц-день.

Разделители

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

  • точка;
  • слэш;
  • дефис;
  • пробел.

Форматы времени

Различие между:

  • 24-часовым форматом;
  • 12-часовым форматом с AM/PM.

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

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

const customLocale = {
  weekdays: {
    shorthand: [...],
    longhand: [...]
  },
  months: {
    shorthand: [...],
    longhand: [...]
  },
  firstDayOfWeek: 1,
  ordinal: (nth) => nth + "й"
};

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

Приоритеты применения локализации

При конфликте настроек применяется следующая иерархия:

  1. параметры экземпляра календаря;
  2. глобальные настройки;
  3. системные дефолты Flatpickr;
  4. встроенные fallback-значения.

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

Отделение UI-локализации от логики ядра

Внутренний движок Flatpickr не использует локализацию для:

  • вычисления диапазонов дат;
  • сравнения значений;
  • фильтрации и валидации.

Все эти операции работают с объектами Date и числовыми таймстампами. Локализация участвует только на этапе:

  • отображения;
  • форматирования;
  • парсинга строкового ввода.

Поведение при частичной локализации

Если локализация неполная, Flatpickr применяет fallback-механизм:

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

Это предотвращает поломку интерфейса при неполных переводах.

Кэширование локалей

После загрузки локаль кэшируется в памяти. Это снижает накладные расходы при:

  • переключении календарей;
  • повторной инициализации компонентов;
  • динамическом изменении интерфейса.

Кэширование позволяет избежать повторного парсинга объектов локализации.

Влияние локализации на доступность интерфейса

Локализация в Flatpickr также влияет на:

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

При этом структура DOM остаётся неизменной, что позволяет использовать одинаковые CSS-стили для всех локалей.

Оглавление