Создание собственной локализации

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

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

Ключевые элементы локализации:

  • названия месяцев;
  • сокращённые и полные названия дней недели;
  • формат и порядок отображения даты;
  • служебные подписи (например, «Сегодня», «Очистить»);
  • правила склонения чисел;
  • настройки 24-часового формата.

Базовая структура пользовательской локали

Любая кастомная локаль строится как объект с фиксированными полями:

const customLocale = {
  weekdays: {
    shorthand: [],
    longhand: []
  },
  months: {
    shorthand: [],
    longhand: []
  },
  firstDayOfWeek: 1,
  ordinal: function (nth) {
    return nth;
  },
  rangeSeparator: " — ",
  weekAbbreviation: "Wk",
  scrollTitle: "Прокрутите для изменения",
  toggleTitle: "Нажмите для переключения",
  amPM: ["AM", "PM"],
  yearAriaLabel: "Год"
};

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

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

Массивы weekdays.shorthand и weekdays.longhand определяют отображение дней недели в интерфейсе календаря.

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

Ключевое требование — соблюдение порядка от воскресенья до субботы, так как Flatpickr использует фиксированную индексацию дней недели.

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

Месяцы задаются аналогично дням недели, с обязательным соответствием индексов от 0 до 11.

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

Ошибки в порядке месяцев приводят к некорректному отображению календаря и смещению дат в UI-слое.

Управление первым днём недели

Параметр firstDayOfWeek определяет, с какого дня начинается календарная сетка.

firstDayOfWeek: 1

Значения:

  • 0 — воскресенье;
  • 1 — понедельник;
  • 6 — суббота.

В локалях большинства стран используется значение 1, что соответствует европейскому стандарту календаря.

Формат порядковых чисел

Функция ordinal позволяет задавать правила отображения порядковых чисел (например, «1-й», «2-й», «3-й»).

ordinal: function (nth) {
  if (nth === 1) return "1-й";
  if (nth === 2) return "2-й";
  if (nth === 3) return "3-й";
  return nth + "-й";
}

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

Разделитель диапазона дат

rangeSeparator отвечает за отображение диапазона дат при выборе периода.

rangeSeparator: " до "

Пример отображения:

01.01.2026 до 10.01.2026

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

Настройка формата AM/PM

Для 12-часового формата используется массив amPM:

amPM: ["ДП", "ПП"]

Первый элемент соответствует времени до полудня, второй — после. При использовании time_24hr: false эти значения становятся частью UI.

Дополнительные текстовые параметры интерфейса

Flatpickr содержит ряд вспомогательных текстов, которые также должны быть локализованы:

scrollTitle: "Прокрутите для изменения",
toggleTitle: "Переключить режим",
weekAbbreviation: "Нед",
yearAriaLabel: "Год"

Эти строки используются в подсказках и aria-атрибутах для доступности интерфейса.

Регистрация собственной локали

Созданный объект необходимо зарегистрировать в Flatpickr через пространство локалей:

import flatpickr from "flatpickr";

const customLocale = {
  weekdays: {
    shorthand: ["Вс", "Пн", "Вт", "Ср", "Чт", "Пт", "Сб"],
    longhand: ["Воскресенье", "Понедельник", "Вторник", "Среда", "Четверг", "Пятница", "Суббота"]
  },
  months: {
    shorthand: ["Янв", "Фев", "Мар", "Апр", "Май", "Июн", "Июл", "Авг", "Сен", "Окт", "Ноя", "Дек"],
    longhand: ["Январь", "Февраль", "Март", "Апрель", "Май", "Июнь", "Июль", "Август", "Сентябрь", "Октябрь", "Ноябрь", "Декабрь"]
  },
  firstDayOfWeek: 1,
  ordinal: n => `${n}-й`,
  rangeSeparator: " до ",
  weekAbbreviation: "Нед",
  scrollTitle: "Прокрутите",
  toggleTitle: "Переключить",
  amPM: ["ДП", "ПП"],
  yearAriaLabel: "Год"
};

flatpickr.l10ns.custom = customLocale;

После регистрации локаль становится доступной через параметр locale.

Применение локали в экземпляре календаря

Использование локали задаётся при инициализации:

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

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

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

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

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

fp.set("locale", "en");

При смене локали пересобирается интерфейс без необходимости пересоздания экземпляра.

Расширение локали на основе существующей

Часто используется стратегия наследования от базовой локали, например английской:

import { English } from "flatpickr/dist/l10n/default";

const extendedLocale = {
  ...English,
  firstDayOfWeek: 1,
  rangeSeparator: " до "
};

flatpickr.l10ns.ruCustom = extendedLocale;

Такой подход уменьшает количество ошибок и упрощает поддержку обновлений библиотеки.

Типовые ошибки при создании локализации

Несоответствие структуры объекта приводит к частичным сбоям интерфейса:

  • пропущенные месяцы или дни недели вызывают смещение индексов;
  • отсутствие firstDayOfWeek ломает сетку календаря;
  • неправильный порядок shorthand/longhand создаёт несоответствие отображения;
  • строковые значения вместо функций в ordinal ограничивают гибкость формата.

Поддержка доступности и ARIA-строк

Отдельное внимание требуется текстам доступности. Flatpickr активно использует ARIA-метки:

yearAriaLabel: "Выбор года",
scrollTitle: "Изменение значения колесом мыши"

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

Оглавление