API эндпоинты

Globalize строится вокруг модульного набора API, которые отражают основные задачи интернационализации: форматирование, парсинг, локализация сообщений и работа с культурными данными. В отличие от монолитных решений, библиотека разделяет функциональность на независимые блоки, каждый из которых опирается на данные CLDR (Unicode Common Locale Data Repository).

Базовая модель API ориентирована не на «готовые глобальные функции», а на явное создание экземпляра локали и последующее использование специализированных методов:

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

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

Инициализация и базовый объект локали

Основной точкой входа является создание экземпляра Globalize с указанием локали:

const globalize = new Globalize("ru");

Этот объект становится контейнером для всех последующих операций. Внутри него не хранится логика форматирования — только привязка к данным CLDR и набору методов.

Важная особенность API: локаль не является «глобальной переменной состояния». Можно создавать несколько независимых экземпляров:

const ru = new Globalize("ru");
const en = new Globalize("en");

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

API форматирования чисел

Модуль чисел является одним из ключевых в Globalize и включает несколько уровней API:

Форматирование обычных чисел

Метод formatNumber реализует локализованное преобразование числа в строку:

globalize.formatNumber(1234567.89);

Результат зависит от локали:

  • в ru: 1 234 567,89
  • в en: 1,234,567.89

Под капотом используются данные CLDR:

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

Форматирование с шаблонами

API поддерживает паттерны:

globalize.formatNumber(1234.5, {
  minimumFractionDigits: 2,
  maximumFractionDigits: 2
});

или через формат-строку:

globalize.formatNumber(1234.5, "0.000");

Форматирование выполняется на основе ICU-подобных правил, что обеспечивает переносимость между локалями.

Парсинг чисел

Обратное преобразование выполняется через parseNumber:

globalize.parseNumber("1 234,56");

API учитывает:

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

API валют

Работа с валютами расширяет числовой модуль и использует CLDR currency data.

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

globalize.formatCurrency(1000, "USD");

Результат:

  • en: $1,000.00
  • ru: 1 000,00 $

API автоматически применяет:

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

Настройка точности

globalize.formatCurrency(99.9, "EUR", {
  minimumFractionDigits: 0,
  maximumFractionDigits: 0
});

Позволяет управлять отображением без вмешательства в локаль.

API дат и времени

Модуль дат в Globalize опирается на CLDR calendar data и предоставляет несколько уровней форматирования.

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

globalize.formatDate(new Date());

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

Явные шаблоны

globalize.formatDate(new Date(), {
  datetime: "medium"
});

Поддерживаемые уровни:

  • short
  • medium
  • long
  • full

Каждый уровень соответствует данным CLDR для конкретной локали.

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

globalize.formatTime(new Date());

Часто используется совместно с датами, но может применяться отдельно для UI-элементов.

Парсинг дат

globalize.parseDate("28.05.2026");

Парсинг зависит от локали и требует наличия соответствующих CLDR-данных календаря.

API относительного времени

Модуль relative time используется для выражений типа «через 5 минут» или «2 дня назад».

globalize.formatRelativeTime(-5, "minute");

Результаты:

  • ru: «5 минут назад»
  • en: «5 minutes ago»

Поддерживаемые единицы:

  • second
  • minute
  • hour
  • day
  • month
  • year

API автоматически выбирает форму на основе правил множественного числа.

API множественного числа

Модуль pluralization использует правила CLDR plural rules.

globalize.plural(5);

Возвращает категорию:

  • one
  • few
  • many
  • other

В зависимости от локали набор категорий может отличаться.

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

const category = globalize.plural(3);

Этот API часто используется как базовый слой для сообщений.

API сообщений (messages)

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

Простые сообщения

globalize.messageFormatter("greeting")();

Данные хранятся отдельно и загружаются через CLDR message bundles.

Интерполяция параметров

const greet = globalize.messageFormatter("welcome");

greet({ name: "Ivan" });

Шаблон:

"welcome": "Привет, {name}"

Поддержка множественных форм

const msg = globalize.messageFormatter("items");

msg({ count: 3 });

Шаблон:

{
  "items": {
    "one": "{count} элемент",
    "few": "{count} элемента",
    "many": "{count} элементов",
    "other": "{count} элемента"
  }
}

API автоматически выбирает форму через plural rules.

API загрузки данных CLDR

Globalize не включает локализационные данные по умолчанию. Работа API зависит от явной загрузки CLDR.

Подключение базовых данных

Globalize.load(
  require("cldr-data/main/ru/numbers"),
  require("cldr-data/main/ru/ca-gregorian"),
  require("cldr-data/supplemental/likelySubtags")
);

Загрузка языков и регионов

CLDR данные разделяются на:

  • main (локаль)
  • supplemental (глобальные правила)

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

API компоновки форматтеров

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

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

const numberFormatter = globalize.numberFormatter();
numberFormatter(12345);

Создание парсера

const numberParser = globalize.numberParser();
numberParser("12 345");

Компилированные функции уменьшают накладные расходы при частом использовании.

API выбора локали и наследование

Каждый экземпляр Globalize связан с конкретной локалью, но может использовать fallback-механизм:

  • ru-KZ → ru → root
  • en-GB → en

API автоматически использует цепочку наследования CLDR данных.

API расширения и интеграции

Globalize предоставляет слой интеграции, позволяющий использовать собственные данные поверх CLDR:

  • пользовательские сообщения
  • кастомные форматы
  • расширенные правила отображения

Расширение не ломает базовую модель, а добавляет новые наборы данных в существующие API-вызовы.

API синхронного и асинхронного использования

Хотя сама библиотека работает синхронно, архитектура загрузки данных подразумевает асинхронный этап подготовки:

  • загрузка JSON CLDR
  • инициализация локали
  • создание форматтеров

После этого все API вызовы становятся синхронными и предсказуемыми.

Внутренняя модель вызовов API

Каждый метод Globalize можно рассматривать как цепочку:

  1. выбор локали
  2. доступ к CLDR данным
  3. применение правил форматирования
  4. возврат строки или объекта

Например, форматирование числа:

formatNumber → CLDR numbers → locale rules → string output

Такой подход делает API детерминированным и независимым от окружения выполнения JavaScript.

Оглавление