@e22m4u/js-localizer

Легковесный сервис локализации для JavaScript.

Содержание

• Установка
• Использование
• Дополнительные утилиты
• Настройки конструктора
• Методы экземпляра
• Тесты
• Лицензия

Установка

npm install @e22m4u/js-localizer

Модуль поддерживает ESM и CommonJS стандарты.

ESM

import {Localizer} from '@e22m4u/js-localizer';

CommonJS

const {Localizer} = require('@e22m4u/js-localizer');

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

Создание экземпляра с указанием словарей и выполнение перевода.

import {Localizer} from '@e22m4u/js-localizer';

// создание экземпляра с указанием словарей
const localizer = new Localizer({
  locale: 'ru',         // текущая локаль (опционально)
  fallbackLocale: 'en', // резервная локаль (опционально, по умолчанию "en")
  dictionaries: {       // словари переводов (опционально)
    en: {
      hello: 'Hello!',
      helloName: 'Hello, %s!',
    },
    ru: {
      hello: 'Привет!',
      helloName: 'Привет, %s!',
    },
  },
});

// перевод по словарю используя ключ
console.log(localizer.t('hello'));             // > Привет!
console.log(localizer.t('helloName', 'Олег')); // > Привет, Олег!

// изменение текущей локали
localizer.setLocale('en');
console.log(localizer.t('helloName', 'Олег')); // > Hello, Олег!

// перевод по языковому объекту (без словарей)
console.log(localizer.o({ru: 'Привет', en: 'Hello'})); // > Hello!

i. Форматирование строк (%s, %d и др.) выполняется с помощью библиотеки @e22m4u/js-format.

Склонения

Для обработки форм множественного числа используется объект с ключами one, few, many.

Пример для русского языка (3 формы)

localizer.setDictionary('ru', {
  iHaveApples: {
    one: 'У меня одно яблоко',
    few: 'У меня %d яблока', // для чисел 2, 3, 4 и дробных
    many: 'У меня %d яблок', // для 0, 5, 6...
  },
});

localizer.setLocale('ru');

console.log(localizer.t('iHaveApples', 1)); // > У меня одно яблоко
console.log(localizer.t('iHaveApples', 3)); // > У меня 3 яблока
console.log(localizer.t('iHaveApples', 5)); // > У меня 5 яблок

Пример для английского языка (2 формы)

Для языков с двумя формами множественного числа (например, английского) достаточно указать one и many (или few). Библиотека автоматически использует вторую форму для всех чисел, кроме 1 и -1.

localizer.setDictionary('en', {
  iHaveApples: {
    one: 'I have an apple',
    many: 'I have %d apples',
  },
});

localizer.setLocale('en');

console.log(localizer.t('iHaveApples', 1));   // > I have an apple
console.log(localizer.t('iHaveApples', 0));   // > I have 0 apples
console.log(localizer.t('iHaveApples', 10));  // > I have 10 apples

Перевод по языковому объекту

Метод o() удобен, когда переводы хранятся не в глобальных словарях, а непосредственно в коде (например, в UI-компоненте).

const localizer = new Localizer({locale: 'ru'});

const title = {
  en: 'Hello!',
  de: 'Hallo!',
  ru: 'Привет!',
};

console.log(localizer.o(title)); // > Привет!

// метод также поддерживает склонения
const counter = {
  en: {one: '%d item', many: '%d items'},
  ru: {one: '%d товар', few: '%d товара', many: '%d товаров'},
};

console.log(localizer.o(counter, 5)); // > 5 товаров

Если перевод для текущей локали отсутствует, будет использована резервная локаль, а если и она недоступна, то будет возвращён перевод для первого найденного языка в объекте. Если подходящий перевод так и не будет найден (например, объект пуст), то метод вернёт пустую строку.

Дополнительные утилиты

Библиотека также экспортирует некоторые полезные функции.

numWords

Функция для выбора правильной формы слова в зависимости от числа. Она используется внутри Localizer, но может быть полезна и сама по себе.

import {numWords} from '@e22m4u/js-localizer';

// для русского языка (3 формы: one, few, many)
numWords(1, 'товар', 'товара', 'товаров');  // > 'товар'
numWords(2, 'товар', 'товара', 'товаров');  // > 'товара'
numWords(5, 'товар', 'товара', 'товаров');  // > 'товаров'

// для английского языка (2 формы: one, few/many)
numWords(1, 'item', 'items'); // > 'item'
numWords(5, 'item', 'items'); // > 'items'
numWords(0, 'item', 'items'); // > 'items'

Настройки конструктора

Параметры передаются в конструктор new Localizer(options).

• locale?: string
  Текущая локаль. Используется как основная локаль для поиска соответствующего словаря или перевода в языковом объекте.
  По умолчанию: undefined

• fallbackLocale?: string
  Резервная локаль. Используется, если перевод для текущей локали не найден или текущая локаль не определена.
  По умолчанию: 'en'

• dictionaries?: LocalizerDictionaries
  Объект со словарями, где ключ - это локаль.
  По умолчанию: {}

Методы экземпляра

• getLocale(): string
  Возвращает текущую локаль. Если текущая локаль не установлена, то возвращается резервная локаль.

• setLocale(locale: string): this
  Устанавливает текущую локаль. Это значение будет иметь приоритет над резервной локалью.

• getFallbackLocale(): string
  Возвращает резервную (альтернативную) локаль. По умолчанию "en".

• setFallbackLocale(locale: string): this
  Устанавливает резервную локаль. Локаль будет использоваться для поиска перевода, если текущая локаль не задана, либо если в словаре текущей локали отсутствует нужный ключ.

• setDictionary(locale: string, dictionary: object): this
  Заменяет словарь для указанной локали.

• t(key: string, ...args: unknown[]): string
  Возвращает переведённую и отформатированную строку по ключу из словаря.

• o(obj: object, ...args: unknown[]): string
  Извлекает и форматирует перевод из переданного объекта для текущей локали.

Тесты

npm test

Лицензия

MIT