Подключение языковых файлов

Flatpickr поддерживает интернационализацию через систему локалей (locales), позволяющую изменять язык интерфейса календаря, форматов дат, названий дней недели и месяцев. Языковые файлы поставляются отдельно от основного ядра библиотеки и подключаются по необходимости, что снижает общий размер бандла при сборке приложения.

Механизм локализации в Flatpickr основан на модульной структуре: каждая локаль представляет собой отдельный JavaScript-модуль, экспортирующий объект с переводами и форматами. Подключение локалей может выполняться несколькими способами в зависимости от архитектуры проекта: через ES-модули, CommonJS, CDN или динамическую загрузку.

Структура языковых файлов

Каждый файл локализации содержит объект с набором параметров:

  • названия месяцев (longhand / shorthand)
  • названия дней недели (longhand / shorthand / initials)
  • текстовые строки интерфейса
  • настройки первого дня недели
  • дополнительные параметры форматирования

Типичная структура локали:

export default {
  weekdays: {
    shorthand: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'],
    longhand: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']
  },
  months: {
    shorthand: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
    longhand: ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']
  },
  firstDayOfWeek: 1,
  rangeSeparator: ' to ',
  weekAbbreviation: 'Wk',
  scrollTitle: 'Scroll to increment',
  toggleTitle: 'Click to toggle'
};

Подключение локали через ES Modules

При использовании сборщиков (Vite, Webpack, Rollup) предпочтительным способом является импорт нужного языка напрямую из пакета.

Импорт конкретной локали

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

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

В данном варианте локаль подключается как объект и передаётся через параметр locale.

Установка глобальной локали

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

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

flatpickr.localize(Russian);

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

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

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

Пример переключения

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

let currentLocale = English;

function setLanguage(lang) {
  if (lang === "ru") {
    currentLocale = Russian;
  } else {
    currentLocale = English;
  }

  flatpickr.localize(currentLocale);
}

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

Локаль на уровне отдельного инстанса

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

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

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

flatpickr("#date-de", {
  locale: German
});

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

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

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

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/flatpickr/dist/flatpickr.min.css">

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

<script>
  flatpickr("#datepicker", {
    locale: "ru"
  });
</script>

При использовании CDN локаль может быть доступна как строковый идентификатор, если соответствующий файл уже загружен.

Использование строкового идентификатора локали

Flatpickr поддерживает передачу локали в виде строки, если она зарегистрирована или подключена:

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

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

Локали и tree-shaking

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

// плохо: импорт всех локалей
import "flatpickr/dist/l10n";

// лучше: только одна локаль
import { Russian } from "flatpickr/dist/l10n/ru.js";

При использовании tree-shaking ненужные языковые файлы исключаются из финальной сборки.

Динамическая загрузка локалей

В приложениях с ленивой загрузкой (lazy loading) локали можно подгружать асинхронно:

import flatpickr from "flatpickr";

async function loadRussianCalendar() {
  const { Russian } = await import("flatpickr/dist/l10n/ru.js");

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

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

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

Некоторые локали могут содержать дополнительные параметры:

  • ordinal — формат порядковых числительных
  • rangeSeparator — разделитель диапазона дат
  • weekAbbreviation — сокращение недели
  • scrollTitle и toggleTitle — текст подсказок

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

Переопределение отдельных значений локали

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

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

const customRussian = {
  ...Russian,
  firstDayOfWeek: 0,
  rangeSeparator: " — "
};

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

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

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

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

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

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

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

Создание собственной локали выполняется через объект с тем же интерфейсом:

const customLocale = {
  firstDayOfWeek: 1,
  weekdays: {
    shorthand: ["Su", "Mo", "Tu", "We", "Th", "Fr", "Sa"],
    longhand: ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]
  },
  months: {
    shorthand: ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"],
    longhand: ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"]
  }
};

flatpickr("#datepicker", {
  locale: customLocale
});

Такая модель используется при интеграции с внутренними системами перевода или CMS.

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

Flatpickr определяет локаль по следующему приоритету:

  1. Локаль, переданная в конкретный инстанс
  2. Глобально установленная через flatpickr.localize
  3. Значение по умолчанию (английская локаль)

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

Оглавление