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

I18next распространяется как npm-пакет и устанавливается стандартными менеджерами зависимостей JavaScript. Библиотека поддерживает работу как в браузере, так и в Node.js, React, Vue, Angular и других экосистемах.

Установка базового пакета

Для установки через npm используется команда:

npm install i18next

После завершения установки пакет появится в разделе dependencies файла package.json:

{
  "dependencies": {
    "i18next": "^25.0.0"
  }
}

Импорт библиотеки в ES Modules:

import i18next from 'i18next';

Импорт в CommonJS:

const i18next = require('i18next');

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

Менеджер пакетов Yarn использует аналогичную схему установки.

Команда установки:

yarn add i18next

После установки зависимость также автоматически записывается в package.json.

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

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

npm list i18next

или:

yarn list i18next

Также версия может быть проверена напрямую через Node.js:

node -p "require('i18next').version"

Минимальная структура проекта

После установки библиотека обычно подключается в отдельном конфигурационном файле.

Пример структуры проекта:

project/
├── src/
│   ├── i18n.js
│   ├── app.js
│   └── locales/
│       ├── en/
│       │   └── translation.json
│       └── ru/
│           └── translation.json
├── package.json
└── node_modules/

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

После установки необходимо выполнить инициализацию экземпляра i18next.

Файл src/i18n.js:

import i18next from 'i18next';

i18next.init({
  lng: 'ru',
  fallbackLng: 'en',

  resources: {
    ru: {
      translation: {
        hello: 'Привет'
      }
    },

    en: {
      translation: {
        hello: 'Hello'
      }
    }
  }
});

export default i18next;

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

import i18next from './i18n.js';

console.log(i18next.t('hello'));

Результат:

Привет

Установка дополнительных модулей

Архитектура i18next построена модульно. Основной пакет предоставляет базовый функционал, а расширения подключаются отдельно.

Наиболее распространённые дополнения:

Модуль Назначение
react-i18next Интеграция с React
i18next-http-backend Загрузка переводов по HTTP
i18next-browser-languagedetector Автоопределение языка браузера
i18next-fs-backend Загрузка переводов из файловой системы
i18next-chained-backend Комбинирование нескольких backend
i18next-icu Поддержка ICU MessageFormat

Установка React-интеграции

Для React используется отдельный пакет:

npm install react-i18next

или:

yarn add react-i18next

Дополнительно почти всегда устанавливается сам i18next, если он ещё отсутствует:

npm install i18next react-i18next

Установка backend для загрузки переводов

Во многих проектах переводы хранятся в JSON-файлах и загружаются динамически.

Установка HTTP backend:

npm install i18next-http-backend

или:

yarn add i18next-http-backend

Подключение:

import i18next from 'i18next';
import Backend from 'i18next-http-backend';

i18next.use(Backend).init({
  lng: 'ru',
  backend: {
    loadPath: '/locales/{{lng}}/{{ns}}.json'
  }
});

Установка автоматического определения языка

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

  • navigator.language
  • cookies
  • localStorage
  • query string
  • subdomain

Установка:

npm install i18next-browser-languagedetector

или:

yarn add i18next-browser-languagedetector

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

import i18next from 'i18next';
import LanguageDetector from 'i18next-browser-languagedetector';

i18next
  .use(LanguageDetector)
  .init({
    fallbackLng: 'en'
  });

Установка нескольких модулей одновременно

npm:

npm install i18next react-i18next i18next-http-backend i18next-browser-languagedetector

Yarn:

yarn add i18next react-i18next i18next-http-backend i18next-browser-languagedetector

Установка в TypeScript-проект

I18next полностью поддерживает TypeScript.

Установка:

npm install i18next

или:

yarn add i18next

Дополнительные типы устанавливать не требуется, поскольку библиотека содержит встроенные TypeScript-определения.

Пример TypeScript-конфигурации:

import i18next from 'i18next';

i18next.init({
  lng: 'ru',
  resources: {
    ru: {
      translation: {
        welcome: 'Добро пожаловать'
      }
    }
  }
});

Установка в Node.js

Для серверных приложений i18next также устанавливается через npm или Yarn.

Установка:

npm install i18next

Пример серверного использования:

const i18next = require('i18next');

i18next.init({
  lng: 'ru',
  resources: {
    ru: {
      translation: {
        error: 'Ошибка сервера'
      }
    }
  }
});

console.log(i18next.t('error'));

Установка файлового backend для Node.js

В серверной среде переводы часто читаются напрямую из файловой системы.

Установка:

npm install i18next-fs-backend

или:

yarn add i18next-fs-backend

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

const i18next = require('i18next');
const Backend = require('i18next-fs-backend');

i18next
  .use(Backend)
  .init({
    lng: 'ru',

    backend: {
      loadPath: './locales/{{lng}}/{{ns}}.json'
    }
  });

Разница между npm и Yarn при установке

Характеристика npm Yarn
Файл блокировки package-lock.json yarn.lock
Скорость установки Высокая Высокая
Менеджер по умолчанию Встроен в Node.js Устанавливается отдельно
Совместимость Полная Полная

I18next одинаково работает в обеих системах управления пакетами.

Установка конкретной версии

Иногда проекту требуется фиксированная версия библиотеки.

Установка определённой версии через npm:

npm install i18next@25.0.0

Через Yarn:

yarn add i18next@25.0.0

Установка dev-зависимости

Хотя i18next обычно относится к production-зависимостям, некоторые вспомогательные инструменты могут устанавливаться как devDependencies.

npm:

npm install --save-dev i18next-parser

Yarn:

yarn add --dev i18next-parser

Очистка и переустановка зависимостей

При повреждении зависимостей выполняется полная переустановка.

Для npm:

rm -rf node_modules package-lock.json
npm install

Для Yarn:

rm -rf node_modules yarn.lock
yarn install

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

Простейший способ убедиться в работоспособности библиотеки — выполнить тестовый скрипт.

Создание файла test.js:

const i18next = require('i18next');

i18next.init({
  lng: 'en',
  resources: {
    en: {
      translation: {
        test: 'I18next works'
      }
    }
  }
});

console.log(i18next.t('test'));

Запуск:

node test.js

Ожидаемый результат:

I18next works

Установка в монорепозитории

В monorepo-проектах библиотека обычно устанавливается в корневом workspace.

Пример для Yarn Workspaces:

yarn workspace frontend add i18next

Для npm workspaces:

npm install i18next --workspace=frontend

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

Ошибка: Cannot find module 'i18next'

Причины:

  • пакет не установлен;
  • повреждён node_modules;
  • используется неправильный package manager;
  • отсутствует запуск npm install.

Решение:

npm install i18next

Ошибка несовместимости ESM и CommonJS

Ошибка:

SyntaxError: Cannot use import statement outside a module

Причина — смешивание модульных систем.

Решение для ESM:

{
  "type": "module"
}

Либо использовать CommonJS:

const i18next = require('i18next');

Ошибка peer dependencies

Некоторые интеграции требуют совместимых версий React или других библиотек.

Проверка:

npm ls

Установка совместимых зависимостей:

npm install react react-dom react-i18next

Удаление библиотеки

Удаление через npm:

npm uninstall i18next

Удаление через Yarn:

yarn remove i18next

Рекомендуемый набор пакетов для современных приложений

Для обычного JavaScript-приложения

npm install i18next i18next-http-backend i18next-browser-languagedetector

Для React-приложения

npm install i18next react-i18next i18next-http-backend i18next-browser-languagedetector

Для Node.js API

npm install i18next i18next-fs-backend

Для TypeScript + React

npm install i18next react-i18next

Проверка структуры после полной установки

Пример итоговой структуры:

project/
├── public/
│   └── locales/
│       ├── en/
│       │   └── translation.json
│       └── ru/
│           └── translation.json
│
├── src/
│   ├── i18n.js
│   ├── App.jsx
│   └── main.jsx
│
├── node_modules/
├── package.json
├── package-lock.json
└── yarn.lock

Файл translation.json:

{
  "title": "Главная страница",
  "button.save": "Сохранить"
}

Пример получения перевода:

i18next.t('button.save');

Результат:

Сохранить
Оглавление