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

Архитектура библиотеки и базовые зависимости

Globalize представляет собой библиотеку интернационализации (i18n), построенную поверх данных CLDR (Common Locale Data Repository). В отличие от решений с «встроенными переводами», Globalize не содержит локализационных данных внутри пакета — все языковые ресурсы подключаются отдельно.

Ключевая особенность архитектуры:

  • CLDR данные предоставляют числовые, календарные, валютные и языковые правила
  • Globalize реализует API форматирования и локализации
  • cldr.js используется для работы с CLDR-структурами
  • дополнительные пакеты подключаются по мере необходимости (number, date, message formatting)

Такой подход обеспечивает модульность, но требует явной подготовки окружения.

Установка через npm

Основной способ подключения — пакетный менеджер npm.

Установка ядра библиотеки:

npm install globalize

Дополнительно требуются данные CLDR, без которых библиотека не функционирует:

npm install cldr-data

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

npm install cldrjs
npm install globalize-compiler

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

  • globalize
  • cldr-data
  • cldrjs

Подключение через ES Modules

При использовании современных сборщиков (Vite, Webpack, Rollup) подключение выполняется через import:

import Globalize from "globalize";
import Cldr from "cldrjs";

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

Подключение CLDR данных

Globalize не содержит языковых пакетов по умолчанию. Необходимые данные импортируются вручную.

Пример подключения базовых данных для английской локали:

import Globalize from "globalize";
import Cldr from "cldrjs";

import likelySubtags from "cldr-data/supplemental/likelySubtags.json";
import plurals from "cldr-data/supplemental/plurals.json";
import timeData from "cldr-data/supplemental/timeData.json";

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

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

Cldr.load(
  likelySubtags,
  plurals,
  timeData,
  numbers,
  currencies,
  caGregorian
);

Инициализация Globalize

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

const globalize = new Globalize("en");

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

Использование через CDN

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

Подключение базового скрипта:

<script src="https://unpkg.com/globalize/dist/globalize.js"></script>

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

<script src="cldr.js"></script>
<script src="cldr-data.js"></script>

Далее выполняется инициализация аналогично модульному варианту.

Подключение в Node.js окружении

Globalize поддерживает использование на сервере, включая SSR-сценарии.

Пример серверной инициализации:

const Globalize = require("globalize");
const Cldr = require("cldrjs");

require("cldr-data").entireSupplemental();
require("cldr-data").entireMainFor("en");

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

Cldr.load(cldrData.entireSupplemental());
Cldr.load(cldrData.entireMainFor("en"));

const globalize = new Globalize("en");

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

Структура CLDR и требования к данным

CLDR содержит несколько категорий данных:

  • main/ — языковые ресурсы (числа, валюты, даты)
  • supplemental/ — вспомогательные правила (множественные формы, временные зоны)

Минимально необходимый набор для работы Globalize:

  • likelySubtags
  • plurals
  • numbers
  • ca-gregorian
  • currencies

Отсутствие любого из этих компонентов нарушает работу соответствующих API.

Разделение функциональности по модулям

Globalize построен модульно. Подключение функционала происходит по мере необходимости:

import Globalize from "globalize";
import "globalize/number";
import "globalize/date";
import "globalize/currency";

После подключения модулей становятся доступны соответствующие методы:

  • форматирование чисел
  • форматирование дат
  • работа с валютами

Проблемы сборки и их источники

При интеграции в сборщики часто возникают следующие ситуации:

1. Отсутствие CLDR данных

Ошибка возникает при вызове форматирования без предварительного Cldr.load().

2. Несовместимость версий

Globalize и cldr-data должны соответствовать друг другу по версии мажорного релиза.

3. Tree-shaking и удаление данных

Некоторые сборщики могут удалять неиспользуемые JSON-файлы, что приводит к частичной загрузке локали.

Организация структуры подключения в проекте

Типовая структура инициализации в приложении:

/i18n
  cldr.js
  globalize.js
  locales/
    en.js
    ru.js

Файл cldr.js отвечает за загрузку данных:

import Cldr from "cldrjs";
import Globalize from "globalize";

import supplemental from "cldr-data/supplemental/*.json";

Cldr.load(supplemental);

Файл globalize.js отвечает за создание экземпляров локалей:

import Globalize from "globalize";

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

Ленивая загрузка локалей

Для крупных приложений используется динамическая подгрузка:

async function loadLocale(locale) {
  const cldrData = await import(`cldr-data/main/${locale}/numbers.json`);
  Cldr.load(cldrData.default);

  return new Globalize(locale);
}

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

Проверка корректности установки

Корректная установка Globalize подтверждается наличием:

  • успешной загрузки CLDR данных
  • отсутствием ошибок CLDR not loaded
  • корректным форматированием чисел и дат

Пример теста:

const globalize = new Globalize("en");

console.log(globalize.numberFormatter()(12345.67));

Особенности работы в современных проектах

Globalize требует явного управления данными локализации, что влияет на архитектуру:

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

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

Оглавление