Глобальные методы

Библиотека Globalize построена вокруг набора высокоуровневых методов, которые обеспечивают форматирование и парсинг данных с учётом локали. Эти методы работают поверх данных Unicode CLDR (Common Locale Data Repository), поэтому корректная инициализация CLDR является обязательным условием их функционирования.

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

Основные типы данных CLDR:

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

Загрузка обычно выполняется через модуль cldr-data:

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

Globalize.load(likelySubtags, currencyData, numbers, timeData);
Globalize.locale("ru");

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

Глобальные методы форматирования чисел

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

formatNumber

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

const globalize = new Globalize("ru");

globalize.formatNumber(1234567.89);
// "1 234 567,89"

Особенности поведения:

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

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

globalize.formatNumber(1500000, { compact: "short" });
// "1,5 млн"

parseNumber

Метод parseNumber выполняет обратное преобразование строки в число.

globalize.parseNumber("1 234 567,89");
// 1234567.89

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

При несовпадении формата результат может быть NaN:

globalize.locale("ru");

globalize.parseNumber("1,234.56");
// NaN (не соответствует русскому формату)

Глобальные методы работы с валютой

formatCurrency

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

const globalize = new Globalize("ru");

globalize.formatCurrency(1999.99, "RUB");
// "1 999,99 ₽"

Основные особенности:

  • автоматическое добавление символа валюты;
  • корректное размещение символа относительно числа;
  • локализованные правила округления;
  • поддержка международных кодов валют (USD, EUR, RUB и др.).

Пример с другой валютой:

globalize.formatCurrency(100, "USD");
// "100,00 $"

При этом правила отображения могут отличаться:

  • символ до числа или после числа;
  • наличие пробела между значением и символом;
  • формат дробной части.

Глобальные методы работы с датами

formatDate

Метод formatDate отвечает за преобразование объекта Date в строку с учётом локали и заданного формата.

const globalize = new Globalize("ru");

globalize.formatDate(new Date(2026, 0, 15), { datetime: "short" });
// "15.01.2026, 00:00"

Поддерживаемые стили форматирования:

  • short — краткий формат;
  • medium — средний;
  • long — расширенный;
  • full — полный формат с детализацией.

Пример расширенного формата:

globalize.formatDate(new Date(), { datetime: "long" });
// "28 мая 2026 г., 14:30:00 GMT+6"

parseDate

Метод parseDate преобразует строку в объект Date.

globalize.parseDate("15.01.2026");
// Date объект

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

Пример с явным форматом:

globalize.parseDate("28 мая 2026 г.", { skeleton: "yMMMMd" });

Если формат не совпадает, результатом будет null.

Глобальные методы работы с сообщениями и плюрализацией

formatMessage

Метод formatMessage используется для интернационализации строк с параметрами.

Сначала определяются сообщения:

Globalize.loadMessages({
  ru: {
    greeting: "Привет, {name}!",
  }
});

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

const globalize = new Globalize("ru");

globalize.formatMessage("greeting", { name: "Алексей" });
// "Привет, Алексей!"

Метод поддерживает:

  • подстановку переменных;
  • вложенные ключи;
  • локализованные шаблоны.

plurals и formatPlural

Globalize учитывает правила множественных форм, зависящие от языка.

Globalize.loadMessages({
  ru: {
    item: "{count, plural, one {# элемент} few {# элемента} many {# элементов} other {# элемента}}"
  }
});

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

globalize.formatMessage("item", { count: 5 });
// "5 элементов"

Механизм основан на CLDR-правилах, поэтому корректно работает для сложных языков с несколькими формами множественного числа.

Глобальная смена локали

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

Globalize.locale("ru");

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

Особенности:

  • глобальная локаль действует как значение по умолчанию;
  • экземпляры new Globalize("en") имеют приоритет над глобальной настройкой;
  • смена локали влияет на кешированные форматы.

Взаимосвязь глобальных методов

Глобальные методы Globalize работают как единая система:

  • formatNumber и parseNumber используют общие числовые правила CLDR;
  • formatDate и parseDate используют временные схемы локали;
  • formatCurrency объединяет числовые и валютные данные CLDR;
  • formatMessage использует правила плюрализации и интерполяции.

Общая архитектура строится вокруг принципа:

  • данные CLDR → локаль → форматирование/парсинг.

Это обеспечивает консистентность поведения всех методов независимо от типа данных.

Поведение при отсутствии данных CLDR

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

  • возможны ошибки при форматировании;
  • результаты могут быть пустыми строками;
  • парсинг возвращает NaN или null.

Поэтому корректная загрузка всех зависимостей CLDR является обязательной частью работы с библиотекой.

Производительность глобальных методов

Globalize использует кэширование форматтеров:

  • повторные вызовы formatNumber с одинаковыми параметрами используют кеш;
  • форматтеры дат создаются один раз на комбинацию локаль/шаблон;
  • сообщения интернационализации компилируются в функции.

Это снижает накладные расходы при массовом форматировании данных, особенно в интерфейсах с большим количеством локализованных элементов.

Оглавление