Минимальный рабочий пример

Библиотека Globalize используется для интернационализации в JavaScript и основана на стандарте CLDR (Unicode Common Locale Data Repository). Основная особенность — отсутствие встроенных локалей: все данные подключаются отдельно, что позволяет собирать минимально необходимый набор ресурсов.

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

npm install globalize
npm install cldr-data

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

Архитектура Globalize и зависимость от CLDR

Globalize не содержит локализационных данных внутри пакета. Вместо этого используется CLDR:

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

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

Минимальный набор данных CLDR

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

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

// загрузка обязательных данных
Globalize.load(
  cldrData.entireSupplemental(),
  cldrData.entireMainFor("en")
);

Ключевой момент

Без загрузки supplemental и main данные форматирование работать не будет, даже если библиотека импортирована корректно.

Инициализация локали

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

const enGlobalize = new Globalize("en");

Строка "en" определяет активную локаль. Для разных языков создаются отдельные экземпляры.

Минимальный рабочий пример форматирования чисел

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

Globalize.load(
  cldrData.entireSupplemental(),
  cldrData.entireMainFor("en")
);

const en = new Globalize("en");

const formattedNumber = en.numberFormatter()(1234567.89);

console.log(formattedNumber);

Результат:

1,234,567.89

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

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

const currencyFormatter = en.currencyFormatter("USD");

console.log(currencyFormatter(1999.99));

Результат:

$1,999.99

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

Globalize использует CLDR-форматы для дат.

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

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

Формат зависит от локали и настроек CLDR.

Минимальный пример сообщений (messages)

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

Подключение сообщений

Globalize.loadMessages({
  en: {
    welcome: "Welcome, {name}!"
  }
});

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

const messageFormatter = en.messageFormatter("welcome");

console.log(messageFormatter({ name: "Alex" }));

Результат:

Welcome, Alex!

Полный минимальный рабочий пример

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

// загрузка CLDR
Globalize.load(
  cldrData.entireSupplemental(),
  cldrData.entireMainFor("en")
);

// сообщения
Globalize.loadMessages({
  en: {
    welcome: "Welcome, {name}!"
  }
});

// инициализация локали
const en = new Globalize("en");

// число
const number = en.numberFormatter()(9876543.21);

// валюта
const currency = en.currencyFormatter("USD")(2500);

// дата
const date = en.dateFormatter({ datetime: "medium" })(new Date());

// сообщение
const message = en.messageFormatter("welcome")({ name: "User" });

console.log(number);
console.log(currency);
console.log(date);
console.log(message);

Использование в браузере

В браузерной среде требуется сборка через bundler (Webpack, Vite, Rollup), так как CLDR-файлы подключаются как модули.

Пример структуры:

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

import supplemental from "cldr-data/supplemental/likelySubtags.json";
import numbers from "cldr-data/main/en/numbers.json";

Globalize.load(supplemental, numbers);

const g = new Globalize("en");

console.log(g.numberFormatter()(1000));

Особенности минимальной конфигурации

Обязательные компоненты

  • cldr-data/supplemental/likelySubtags
  • cldr-data/supplemental/numberingSystems
  • cldr-data/main/<locale>/*

Частые причины ошибок

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

Структура минимального пайплайна

  1. Установка globalize и cldr-data
  2. Загрузка CLDR в память
  3. Подключение сообщений (при необходимости)
  4. Создание экземпляра Globalize(locale)
  5. Использование форматтеров

Инициализация нескольких локалей

Globalize допускает параллельное использование разных локалей:

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

console.log(en.numberFormatter()(1234.5));
console.log(de.numberFormatter()(1234.5));
console.log(ru.numberFormatter()(1234.5));

Каждая локаль использует собственные данные CLDR, если они загружены.

Оглавление