Инициализация библиотеки

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

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

Установка через пакетный менеджер

В современных проектах библиотека устанавливается через npm:

npm install globalize

Дополнительно почти всегда требуется установка набора данных CLDR:

npm install cldr-data

Пакет cldr-data содержит локализованные наборы чисел, дат, валют, правил плюрализации и других региональных особенностей.

Подключение модулей в проект

Globalize поддерживает модульный импорт. В зависимости от среды используется CommonJS или ES Modules.

ES Modules

import Globalize from "globalize";
import cldrData from "cldr-data";

CommonJS

const Globalize = require("globalize");
const cldrData = require("cldr-data");

Важно учитывать, что сам пакет Globalize не содержит данных локализации, поэтому подключение cldr-data является обязательным этапом.

Структура и роль CLDR

CLDR — это база данных локализации, предоставляющая:

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

Globalize использует эти данные как основу. Без загрузки CLDR большинство функций библиотеки работать не будут.

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

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

Базовые данные

import likelySubtags from "cldr-data/supplemental/likelySubtags.json";
import currencyData from "cldr-data/supplemental/currencyData.json";
import numberingSystems from "cldr-data/supplemental/numberingSystems.json";

Локальные данные для конкретной локали

Пример для английской и русской локалей:

import enNumbers from "cldr-data/main/en/numbers.json";
import enCurrencies from "cldr-data/main/en/currencies.json";
import enCaGregorian from "cldr-data/main/en/ca-gregorian.json";

import ruNumbers from "cldr-data/main/ru/numbers.json";
import ruCurrencies from "cldr-data/main/ru/currencies.json";
import ruCaGregorian from "cldr-data/main/ru/ca-gregorian.json";

Инициализация CLDR внутри Globalize

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

Globalize.load(
  likelySubtags,
  currencyData,
  numberingSystems,
  enNumbers,
  enCurrencies,
  enCaGregorian,
  ruNumbers,
  ruCurrencies,
  ruCaGregorian
);

Метод Globalize.load принимает любое количество JSON-объектов CLDR и объединяет их в внутреннем хранилище библиотеки.

Установка активной локали

После загрузки данных необходимо указать локаль, с которой будет работать экземпляр Globalize.

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

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

Проверка корректности инициализации

Базовым способом проверки корректности загрузки является форматирование числа:

const formatted = globalizeEn.numberFormatter()(1234567.89);
console.log(formatted);

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

Инициализация через динамическую загрузку данных

В браузерных приложениях данные CLDR часто загружаются асинхронно.

Пример загрузки через fetch

async function loadCldrData() {
  const [likelySubtags, numberingSystems, currencyData] = await Promise.all([
    fetch("/cldr/supplemental/likelySubtags.json").then(r => r.json()),
    fetch("/cldr/supplemental/numberingSystems.json").then(r => r.json()),
    fetch("/cldr/supplemental/currencyData.json").then(r => r.json())
  ]);

  Globalize.load(likelySubtags, numberingSystems, currencyData);
}

После загрузки базовых данных добавляются локальные ресурсы:

async function loadLocaleData(locale) {
  const [numbers, currencies, calendar] = await Promise.all([
    fetch(`/cldr/main/${locale}/numbers.json`).then(r => r.json()),
    fetch(`/cldr/main/${locale}/currencies.json`).then(r => r.json()),
    fetch(`/cldr/main/${locale}/ca-gregorian.json`).then(r => r.json())
  ]);

  Globalize.load(numbers, currencies, calendar);
}

Создание экземпляра после асинхронной инициализации

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

const globalize = new Globalize("ru");

const dateFormatter = globalize.dateFormatter({
  datetime: "medium"
});

console.log(dateFormatter(new Date()));

Важные зависимости и порядок загрузки

Порядок инициализации критичен:

  1. Подключение Globalize
  2. Загрузка CLDR supplemental данных
  3. Загрузка локальных данных
  4. Вызов Globalize.load
  5. Создание экземпляра с локалью
  6. Использование форматтеров

Нарушение этого порядка приводит к ошибкам форматирования или отсутствию локализационных правил.

Использование bundler-архитектуры

При работе с Webpack или Vite данные CLDR могут быть импортированы напрямую:

import Globalize from "globalize";

import "cldr-data/supplemental/likelySubtags.json";
import "cldr-data/supplemental/numberingSystems.json";
import "cldr-data/supplemental/currencyData.json";

Далее выполняется единая загрузка:

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

Такой подход увеличивает размер бандла, но упрощает инициализацию.

Типовые ошибки инициализации

Отсутствие supplemental данных

Без likelySubtags и numberingSystems многие операции не могут определить корректную локаль и форматирование.

Частичная загрузка локали

Если загружены только числа, но отсутствуют календарные данные, форматирование дат будет некорректным.

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

Создание new Globalize("ru") без загрузки ru-данных приводит к падению форматтеров или возврату сырых значений.

Архитектурная модель инициализации

Внутренне Globalize работает по следующей схеме:

  • CLDR хранится в общем контейнере
  • экземпляры Globalize используют ссылку на этот контейнер
  • форматтеры создаются лениво (lazy evaluation)
  • данные не дублируются между экземплярами

Это означает, что загрузка CLDR выполняется один раз, а все локали используют единый источник данных.

Минимальный корректный набор для запуска

Для полноценной работы с числами, валютами и датами требуется следующий минимум:

  • likelySubtags.json
  • numberingSystems.json
  • currencyData.json
  • numbers.json (для нужной локали)
  • currencies.json (для нужной локали)
  • ca-gregorian.json (для нужной локали)
Оглавление