API референс

Основной точкой входа в архитектуре FormatJS является провайдер интернационализации, предоставляющий доступ ко всем API форматирования через React-контекст.

IntlProvider (react-intl)

Компонент из react-intl отвечает за инициализацию и распространение i18n-контекста.

Сигнатура:

<IntlProvider
  locale={string}
  messages={Record<string, string>}
  defaultLocale?: string
  timeZone?: string
  formats?: object
  textComponent?: React.ComponentType
  wrapRichTextChunksInFragment?: boolean
  onError?: (err: Error) => void
>

Параметры:

  • locale — текущая локаль (например, "en", "ru", "fr-CA").
  • messages — словарь переводов ключ → строка.
  • defaultLocale — локаль по умолчанию для fallback-логики.
  • timeZone — временная зона для форматирования дат.
  • formats — преднастроенные форматы чисел, дат, времени.
  • textComponent — обёртка для текстовых узлов.
  • onError — обработчик ошибок интернационализации.

Контекст, создаваемый провайдером, содержит объект intl, доступный во всех дочерних компонентах.

useIntl: основной хук API

useIntl()

Возвращает объект IntlShape, предоставляющий доступ ко всем функциям форматирования.

Сигнатура:

const intl = useIntl();

IntlShape включает:

  • formatMessage
  • formatDate
  • formatTime
  • formatDateTime
  • formatNumber
  • formatPlural
  • formatRelativeTime
  • formatDisplayName
  • locale
  • messages

formatMessage

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

Сигнатура:

intl.formatMessage(
  descriptor: MessageDescriptor,
  values?: Record<string, string | number | Date | React.ReactNode>
): string

MessageDescriptor:

{
  id: string;
  defaultMessage?: string;
  description?: string;
}

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

intl.formatMessage(
  { id: "user.greeting", defaultMessage: "Hello, {name}" },
  { name: "Alex" }
);

Поддерживает:

  • интерполяцию переменных
  • плюрализацию ICU-синтаксиса
  • форматирование вложенных сущностей

ICU MessageFormat синтаксис

Базовый слой форматирования основан на ICU MessageFormat.

Параметры

Hello, {name}

Плюрализация

{count, plural,
  one {1 item}
  other {# items}
}

Выбор (sel ect)

{gender, select,
  male {He}
  female {She}
  other {They}
}

Числовой placeholder

Balance: {amount, number, currency}

formatDate / formatTime / formatDateTime

Методы для локализованного форматирования дат.

formatDate

intl.formatDate(value, options?)

Параметры:

  • value: Date | number | string
  • options: Intl.DateTimeFormatOptions

Пример:

intl.formatDate(new Date(), {
  year: "numeric",
  month: "long",
  day: "2-digit"
});

formatTime

intl.formatTime(value, options?)

Использует Intl.DateTimeFormat под капотом.

formatDateTime

Комбинированное форматирование даты и времени.

intl.formatDateTime(value, options?)

formatNumber

Унифицированное числовое форматирование через Intl.NumberFormat.

intl.formatNumber(value, options?)

Примеры:

Валюта

intl.formatNumber(1200, {
  style: "currency",
  currency: "USD"
});

Проценты

intl.formatNumber(0.25, {
  style: "percent"
});

Обычное число

intl.formatNumber(1000000);

formatPlural

Метод выбора формы слова на основе количества.

intl.formatPlural(value, options?)

Возвращает: "zero" | "one" | "two" | "few" | "many" | "other"

Пример:

intl.formatPlural(3, {
  one: "item",
  other: "items"
});

formatRelativeTime

Относительное время (вчера, 2 часа назад).

intl.formatRelativeTime(value, unit, options?)

Параметры:

  • value: number
  • unit: "second" | "minute" | "hour" | "day" | "month" | "year"

Пример:

intl.formatRelativeTime(-5, "day");

formatDisplayName

Форматирование локализованных названий языков, регионов и валют.

intl.formatDisplayName(value, type)

type:

  • "language"
  • "region"
  • "currency"
  • "script"

Пример:

intl.formatDisplayName("en", "language");

createIntl и низкоуровневый API

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

createIntl

import { createIntl, createIntlCache } fr om "react-intl";

Сигнатура:

const intl = createIntl({
  locale: "en",
  messages: {}
}, cache);

createIntlCache

Кэширование форматтеров для повышения производительности.

const cache = createIntlCache();

MessageDescriptor и типизация сообщений

Структура описания сообщений является базовым контрактом системы.

type MessageDescriptor = {
  id: string;
  defaultMessage?: string;
  description?: string;
};

defineMessages

Утилита группировки сообщений.

defineMessages({
  title: {
    id: "page.title",
    defaultMessage: "Home"
  },
  subtitle: {
    id: "page.subtitle",
    defaultMessage: "Welcome"
  }
});

Rich Text Formatting

API позволяет вставлять React-узлы в локализованные строки.

Пример:

intl.formatMessage(
  {
    id: "terms",
    defaultMessage: "Accept the <b>terms</b>"
  },
  {
    b: (chunks) => <strong>{chunks}</strong>
  }
);

Поддерживаемые конструкции:

  • inline bold/italic
  • ссылки
  • кастомные компоненты

Error handling API

onError

Глобальный обработчик ошибок форматирования.

<IntlProvider
  locale="en"
  messages={{}}
  onEr ror={(err) => {
    console.log(err);
  }}
/>

Типовые ошибки:

  • отсутствующий message id
  • некорректный ICU синтаксис
  • несовпадение типов значений

IntlShape: структура объекта intl

Ключевой объект API:

type IntlShape = {
  locale: string;
  messages: Record<string, string>;
  formatMessage: Function;
  formatNumber: Function;
  formatDate: Function;
  formatTime: Function;
  formatDateTime: Function;
  formatPlural: Function;
  formatRelativeTime: Function;
  formatDisplayName: Function;
}

Каждый метод является обёрткой над стандартными ECMA-402 Intl API с дополнительным слоем ICU логики.

ICU Message compilation и intl-messageformat

Внутри системы используется компилятор сообщений, реализованный в пакете messageformat.

Он выполняет:

  • парсинг ICU строк
  • построение AST
  • генерацию функции форматирования
  • кэширование результата

Пример внутреннего представления:

"Hello {name}"
→ AST → функции интерполяции

Системы fallback и наследование локалей

Локализация работает по цепочке:

  1. точная локаль (ru-KZ)
  2. базовая локаль (ru)
  3. defaultLocale
  4. defaultMessage

Пример поведения:

  • отсутствует перевод → используется defaultMessage
  • отсутствует defaultMessage → возвращается id

Форматтеры Intl API как базовый слой

Вся система опирается на стандартные API ECMAScript:

  • Intl.NumberFormat
  • Intl.DateTimeFormat
  • Intl.PluralRules
  • Intl.RelativeTimeFormat
  • Intl.DisplayNames

FormatJS расширяет их, добавляя ICU слой и React-интеграцию.

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

Ключевые оптимизации:

  • reuse Intl.* экземпляров
  • memoization через createIntlCache
  • precompilation сообщений
  • избегание пересоздания formatter объектов

Паттерн:

const cache = createIntlCache();
const intl = createIntl(config, cache);

Типизация и интеграция с TypeScript

Поддерживаются строгие типы сообщений:

type Messages = {
  "app.title": string;
  "app.description": string;
};

Интеграция позволяет:

  • проверять существование message id
  • типизировать параметры интерполяции
  • предотвращать runtime ошибки форматирования
Оглавление