Утилиты

Globalize опирается на модель работы, в которой прикладные функции форматирования и парсинга отделены от данных локализации. Утилиты библиотеки обеспечивают загрузку CLDR-данных, управление локалью, доступ к механизмам разрешения правил и единый контекст выполнения для форматирования чисел, дат, сообщений и единиц измерения.

Управление локалью и контекст выполнения

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

Установка и получение локали

Globalize.locale("ru");
const locale = Globalize.locale();

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

Загрузка CLDR-данных

Globalize не содержит локализационных данных по умолчанию. Утилиты загрузки отвечают за подключение CLDR JSON-файлов, без которых невозможны операции форматирования.

Основные категории данных:

  • numbers (форматы чисел, десятичные разделители)
  • dates (календари, периоды времени)
  • units (единицы измерения)
  • plural (правила множественного числа)
  • likelySubtags (определение полной локали)

Базовый механизм загрузки

Globalize.load(
  require("cldr-data").entireSupplemental(),
  require("cldr-data").entireMainFor("ru")
);

Загрузка выполняется один раз, после чего данные кэшируются внутри runtime.

Утилиты разрешения данных CLDR

После загрузки CLDR доступ к данным осуществляется через вспомогательные функции:

Доступ к сырым данным

Globalize.cldr.attributes
Globalize.cldr.get("supplemental/likelySubtags")

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

Форматирование чисел как утилитарный слой

Форматирование чисел реализуется через цепочку утилит:

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

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

const formatNumber = Globalize("ru").numberFormatter();

formatNumber(12345.67);

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

const parseNumber = Globalize("ru").numberParser();

parseNumber("12 345,67");

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

Утилиты работы с датами

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

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

const formatDate = Globalize("ru").dateFormatter({ datetime: "medium" });

formatDate(new Date());

Парсинг даты

const parseDate = Globalize("ru").dateParser({ datetime: "medium" });

parseDate("28.05.2026, 14:30");

Утилиты учитывают:

  • локальный календарь
  • порядок компонентов даты
  • разделители
  • формат времени (12/24 часа)

Механизм сообщений как утилита интерполяции

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

Форматирование сообщений

const messageFormatter = Globalize("ru").messageFormatter(
  "У пользователя {count} {count, plural, one {сообщение} few {сообщения} many {сообщений} other {сообщения}}"
);

messageFormatter({ count: 5 });

Утилиты сообщений включают:

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

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

Механизм plural rules является отдельным утилитарным компонентом, используемым в сообщениях и форматировании.

Определение категории

const plural = Globalize("ru").pluralGenerator();

plural(1);
plural(2);
plural(5);

Результатом является категория:

  • one
  • few
  • many
  • other

Эти категории определяются CLDR-правилами для каждой локали.

Утилиты единиц измерения

Модуль единиц измерения использует CLDR unit patterns и предоставляет функции форматирования.

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

const formatUnit = Globalize("ru").unitFormatter("kilometer");

formatUnit(10);

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

  • длина
  • масса
  • температура
  • объем
  • скорость

Утилита автоматически выбирает правильную форму слова в зависимости от локали и числа.

Утилиты выбора форматов (Skeleton API)

Skeleton API служит утилитой декларативного описания формата без жесткой привязки к конкретному паттерну.

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

const formatNumber = Globalize("ru").numberFormatter({
  skeleton: "currency"
});

Skeleton преобразуется в конкретный формат на основе CLDR данных.

Основные утилитарные преимущества:

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

Утилиты нормализации локалей

Внутренние механизмы Globalize используют функции нормализации:

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

Пример логики:

ru-KZ → ru → root

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

Кэширование форматтеров как утилитарный слой

Создание форматтеров является дорогой операцией, поэтому используется кэширование.

const g = Globalize("ru");

const f1 = g.numberFormatter();
const f2 = g.numberFormatter();

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

Кэшируются:

  • numberFormatter
  • dateFormatter
  • messageFormatter
  • unitFormatter

Утилиты преобразования входных данных

Перед форматированием данные проходят нормализацию:

  • приведение типов
  • обработка NaN
  • очистка строк
  • приведение дат к Date объекту

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

const formatNumber = Globalize("ru").numberFormatter();

formatNumber("12345"); // корректная обработка строки

Вспомогательные механизмы разрешения паттернов

Globalize использует утилиты выбора паттернов:

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

Пример:

Globalize("ru").dateFormatter({ date: "short" });
Globalize("ru").dateFormatter({ date: "long" });

Утилиты работы с fallback и отсутствующими данными

При отсутствии данных CLDR применяются стратегии:

  • переход к базовой локали
  • использование нейтральных форм
  • применение default patterns

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

Инструменты интеграции с внешними данными

Globalize предоставляет утилитарный слой для подключения внешних источников CLDR:

  • загрузка модулей через bundler
  • динамическое подключение JSON
  • совместимость с Node.js и браузером

Пример структуры подключения:

import Globalize from "globalize";
import likelySubtags from "cldr-data/supplemental/likelySubtags.json";
import numbers from "cldr-data/main/ru/numbers.json";

Globalize.load(likelySubtags, numbers);

Утилиты диагностики и отладки

Внутренние механизмы позволяют анализировать поведение локализации:

  • проверка загруженных CLDR пакетов
  • анализ доступных форматов
  • тестирование fallback-цепочек

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

Оглавление