Локализация дат

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

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

Понятие локали

Локаль (locale) — это набор правил, определяющих формат представления информации для определённого региона и языка. Обычно она обозначается строкой вида:

language-REGION

Примеры:

Локаль Язык Регион
en-US английский США
en-GB английский Великобритания
fr-FR французский Франция
de-DE немецкий Германия
ru-RU русский Россия
ja-JP японский Япония

Локаль влияет на:

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

Например:

Локаль Отображение даты
en-US 03/12/2026
en-GB 12/03/2026
de-DE 12.03.2026
ru-RU 12.03.2026

React Aria автоматически учитывает локаль при форматировании дат.

Архитектура локализации в React Aria

Локализация строится на нескольких компонентах:

1. React Aria

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

2. React Stately

Управляет состоянием календарных компонентов.

3. Internationalized Date

Библиотека @internationalized/date предоставляет:

  • универсальные типы дат
  • поддержку календарей
  • операции над датами
  • интернационализацию

4. React Aria i18n

Пакет @react-aria/i18n обеспечивает:

  • определение текущей локали
  • передачу локали в компоненты
  • форматирование дат и чисел

Provider локали

Контекст локализации передаётся через I18nProvider.

Импорт

import {I18nProvider} from '@react-aria/i18n'

Использование

<I18nProvider locale="ru-RU">
  <App />
</I18nProvider>

Теперь все компоненты внутри дерева получают локаль ru-RU.

Пример:

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

Определение локали пользователя

Часто локаль определяется автоматически.

Через браузер

navigator.language

Пример значения:

en-US
ru-RU
fr-FR

Использование в приложении

<I18nProvider locale={navigator.language}>
  <App />
</I18nProvider>

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

Получение текущей локали

React Aria предоставляет хук useLocale.

Импорт

import {useLocale} from '@react-aria/i18n'

Использование

function Example() {
  let {locale, direction} = useLocale()

  return (
    <div>
      Current locale: {locale}
    </div>
  )
}

Возвращаемые значения:

Поле Назначение
locale текущая локаль
direction направление текста

Направление текста

Некоторые языки используют правостороннее направление письма.

Примеры:

Язык Направление
английский LTR
русский LTR
арабский RTL
иврит RTL

useLocale возвращает:

direction: "ltr"

или

direction: "rtl"

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

Библиотека @internationalized/date

React Aria использует собственную библиотеку для работы с датами:

@internationalized/date

Она решает ряд проблем стандартного Date:

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

Библиотека вводит типы:

Тип Назначение
CalendarDate дата без времени
CalendarDateTime дата + время
ZonedDateTime дата + время + часовой пояс
Time только время

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

Форматирование выполняется через DateFormatter.

Импорт

import {DateFormatter} from '@internationalized/date'

Создание форматтера

let formatter = new DateFormatter('ru-RU', {
  dateStyle: 'long'
})

Пример использования

import {CalendarDate} from '@internationalized/date'

let date = new CalendarDate(2026, 3, 12)

formatter.format(date.toDate())

Результат:

12 марта 2026 г.

Опции форматирования

DateFormatter поддерживает стандарт Intl.DateTimeFormat.

Основные параметры

Параметр Описание
dateStyle стиль даты
timeStyle стиль времени
weekday день недели
year год
month месяц
day день

dateStyle

Возможные значения:

short
medium
long
full

Пример:

new DateFormatter('ru-RU', {
  dateStyle: 'short'
})

Результат:

12.03.26

long

new DateFormatter('ru-RU', {
  dateStyle: 'long'
})

Результат:

12 марта 2026 г.

full

new DateFormatter('ru-RU', {
  dateStyle: 'full'
})

Результат:

четверг, 12 марта 2026 г.

Кастомное форматирование

Можно задавать точные параметры.

Пример

new DateFormatter('ru-RU', {
  day: 'numeric',
  month: 'long',
  year: 'numeric'
})

Результат:

12 марта 2026

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

React Aria автоматически локализует названия месяцев.

Пример:

Локаль Месяц
en-US March
ru-RU март
fr-FR mars
de-DE März

Это особенно важно для календарных компонентов.

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

Локаль также определяет названия дней недели.

Локаль Monday
en-US Monday
ru-RU понедельник
fr-FR lundi
de-DE Montag

Начало недели

В разных странах неделя начинается с разных дней.

Регион Первый день недели
США воскресенье
Европа понедельник
Ближний Восток суббота

React Aria определяет это автоматически на основе локали.

Работа с календарными системами

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

Поддерживаются:

Календарь Регион
Gregorian большинство стран
Japanese Япония
Buddhist Таиланд
Islamic исламские страны
Hebrew Израиль

Пример создания календарной даты

import {CalendarDate} from '@internationalized/date'

let date = new CalendarDate(2026, 3, 12)

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

Конвертация в JavaScript Date

Иногда требуется стандартный объект Date.

Пример

date.toDate('UTC')

Результат:

JavaScript Date

Форматирование диапазона дат

React Aria поддерживает форматирование диапазонов.

Пример

let formatter = new DateFormatter('ru-RU', {
  dateStyle: 'medium'
})

formatter.formatRange(
  new Date(2026, 2, 10),
  new Date(2026, 2, 15)
)

Результат:

10–15 мар. 2026

Это используется в:

  • календарях выбора диапазона
  • бронированиях
  • планировании событий

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

Компоненты React Aria автоматически используют текущую локаль.

Пример:

Calendar
DatePicker
RangeCalendar

Они локализуют:

  • месяцы
  • дни недели
  • формат даты
  • начало недели

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

<I18nProvider locale="ru-RU">
  <Calendar />
</I18nProvider>

Интерфейс будет отображать:

Март 2026
Пн Вт Ср Чт Пт Сб Вс

Динамическая смена локали

Локаль можно менять во время работы приложения.

Пример

const [locale, setLocale] = useState("en-US")

Переключение

<I18nProvider locale={locale}>
  <App />
</I18nProvider>

Кнопки переключения

<button onCl ick={() => setLocale("ru-RU")}>
  Русский
</button>

<button onCl ick={() => setLocale("en-US")}>
  English
</button>

После переключения:

  • календарь
  • формат дат
  • названия месяцев

изменятся автоматически.

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

DateFormatter также форматирует время.

Пример

new DateFormatter('ru-RU', {
  timeStyle: 'short'
})

Результат:

14:30

Полная дата и время

new DateFormatter('ru-RU', {
  dateStyle: 'long',
  timeStyle: 'short'
})

Результат:

12 марта 2026 г., 14:30

Часовые пояса

При работе с датами важно учитывать timezone.

React Aria поддерживает ZonedDateTime.

Пример

import {ZonedDateTime} from '@internationalized/date'

Это позволяет:

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

Практические рекомендации

Использование CalendarDate

Для календарных компонентов лучше использовать:

CalendarDate

а не Date.

Это избегает проблем с часовыми поясами.

Передача локали через Provider

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

I18nProvider

Это гарантирует согласованность интерфейса.

Не использовать ручное форматирование

Плохой подход:

12/03/2026

Правильный:

DateFormatter

Это автоматически адаптирует формат под локаль.

Использование Intl стандартов

React Aria построен поверх:

Intl.DateTimeFormat

Это обеспечивает:

  • корректную локализацию
  • поддержку всех современных браузеров
  • единое поведение во всех регионах

Частые ошибки

Использование JavaScript Date напрямую

Date зависит от:

  • timezone
  • локали системы
  • реализации браузера

Это приводит к ошибкам в календарях.

Игнорирование локали

Жёстко заданные форматы:

MM/DD/YYYY

работают только для США.

Неправильное начало недели

Некоторые разработчики всегда начинают неделю с понедельника, что неверно для ряда стран.

React Aria автоматически определяет правильное значение.

Результат использования локализации React Aria

Корректная локализация обеспечивает:

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

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

Оглавление