Первый рабочий пример

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

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

npm install i18next

В типичном браузерном или Node.js-проекте этого достаточно, чтобы получить доступ к основным возможностям библиотеки. Дополнительно могут потребоваться интеграции (например, для React или backend-фреймворков), но базовая логика работает на чистом ядре.

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

Инициализация экземпляра i18next

Основой работы является объект i18n, создаваемый через функцию init. Он хранит текущий язык, словари и настройки поведения.

import i18next from 'i18next';

i18next.init({
  lng: 'en',
  debug: true,
  resources: {}
});

Параметр lng определяет текущий язык интерфейса. В данном случае выбран английский. Параметр resources пока пустой, так как словари добавляются отдельно.

Включение debug: true активирует логирование внутренних процессов: загрузку переводов, выбор ключей, fallback-механизмы.

Добавление первого словаря переводов

Переводы в i18next организованы в виде структуры ресурсов, где каждый язык содержит набор namespace и ключей.

Минимальный словарь выглядит следующим образом:

i18next.init({
  lng: 'en',
  debug: true,
  resources: {
    en: {
      translation: {
        hello: "Hello world",
        welcome: "Welcome to the system"
      }
    },
    ru: {
      translation: {
        hello: "Привет, мир",
        welcome: "Добро пожаловать в систему"
      }
    }
  }
});

Каждый язык (en, ru) содержит namespace translation, внутри которого располагаются ключи перевода. Такая структура является базовой и используется по умолчанию.

Первый вызов перевода

После инициализации становится доступен метод t, отвечающий за получение перевода по ключу.

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

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

Hello world

Если изменить язык на русский:

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

Результат:

Привет, мир

Метод changeLanguage динамически переключает контекст перевода без необходимости переинициализации библиотеки.

Механизм поиска ключей

При вызове t('hello') система выполняет последовательный поиск:

  1. Проверка текущего языка (lng)
  2. Поиск ключа в namespace translation
  3. При отсутствии — переход к fallback-языку
  4. Если ключ не найден — возврат самого ключа

Пример поведения при отсутствии перевода:

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

Результат:

non_existing_key

Это поведение позволяет быстро выявлять пропущенные переводы в процессе разработки.

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

Хотя базовый пример использует один namespace, архитектура i18next предполагает разделение переводов по областям приложения.

Расширенный вариант структуры:

resources: {
  en: {
    common: {
      hello: "Hello",
    },
    auth: {
      login: "Login",
    }
  }
}

Вызов с указанием namespace:

i18next.t('login', { ns: 'auth' });

Если namespace не указан, используется defaultNS, который равен translation, если не переопределён.

Настройка fallback языка

Fallback-язык используется в случае отсутствия перевода в текущей локали.

i18next.init({
  lng: 'ru',
  fallbackLng: 'en',
  resources: {
    en: {
      translation: {
        hello: "Hello"
      }
    },
    ru: {
      translation: {}
    }
  }
});

При вызове:

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

будет возвращено:

Hello

Система автоматически переключается на английский словарь.

Подключение через отдельную конфигурацию

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

// i18n.js
import i18next from 'i18next';

i18next.init({
  lng: 'en',
  fallbackLng: 'en',
  resources: {
    en: {
      translation: {
        hello: "Hello"
      }
    },
    ru: {
      translation: {
        hello: "Привет"
      }
    }
  }
});

export default i18next;

Использование в другом файле:

import i18n from './i18n';

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

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

Асинхронная природа инициализации

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

i18next.init({
  lng: 'en'
}, (err, t) => {
  console.log(t('hello'));
});

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

Поведение при изменении языка во время работы

Смена языка влияет на все последующие вызовы t:

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

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

Вывод изменяется динамически без пересоздания экземпляра.

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

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

Типовая схема первого рабочего примера включает:

  • установка i18next
  • инициализацию через init
  • определение resources
  • использование t для получения строк
  • переключение языка через changeLanguage

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

Обработка вложенных ключей

Даже в первом примере поддерживаются вложенные структуры:

resources: {
  en: {
    translation: {
      user: {
        name: "Name",
        profile: "Profile"
      }
    }
  }
}

Доступ:

console.log(i18next.t('user.name'));

Результат:

Name

Разделение по точечной нотации позволяет масштабировать словари без потери читаемости.

Интерполяция значений в базовом виде

Поддерживается подстановка переменных:

resources: {
  en: {
    translation: {
      greet: "Hello, {{name}}"
    }
  }
}

Вызов:

console.log(i18next.t('greet', { name: 'Alex' }));

Результат:

Hello, Alex

Интерполяция обрабатывается на уровне движка переводов и не требует дополнительной логики в коде приложения.

Оглавление