Интернационализация (i18n) в TypeScript: полное руководство

Интернационализация (i18n) в TypeScript: обзор инструментов и практик

Интернационализация (i18n) — это процесс проектирования программного обеспечения, позволяющий адаптировать его под различные языки и региональные стандарты без изменений в исходном коде. Для TypeScript-приложений выбор подходящей библиотеки i18n критически важен: от него зависит типобезопасность переводов, производительность и удобство поддержки. В этой статье мы рассмотрим три основных подхода и инструмента для реализации i18n в TypeScript.

1. i18next — классическое решение

i18next — самая популярная библиотека для интернационализации в экосистеме JavaScript/TypeScript. Она поддерживает множество фреймворков (React, Vue, Angular) и имеет обширную экосистему плагинов.

Установка:

npm install i18next i18next-browser-languagedetector

Базовая настройка с TypeScript:

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';

// Типизация ресурсов перевода
declare module 'i18next' {
  interface CustomTypeOptions {
    defaultNS: 'common';
    resources: {
      common: typeof import('./locales/en/common.json');
    };
  }
}

i18n.use(initReactI18next).init({
  resources: {
    en: { common: require('./locales/en/common.json') },
    ru: { common: require('./locales/ru/common.json') },
  },
  lng: 'ru',
  fallbackLng: 'en',
  interpolation: { escapeValue: false },
});

export default i18n;

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

import { useTranslation } from 'react-i18next';

function Greeting() {
  const { t } = useTranslation();
  const userName = 'Анна';
  
  return (
    <div>
      <p>{t('greeting', { name: userName })}</p>
      <p>{t('itemsCount', { count: 5 })}</p>
    </div>
  );
}

Плюсы:

• Огромное сообщество и документация
• Поддержка множественного числа (pluralization)
• Интерполяция переменных
• Динамическая загрузка языковых ресурсов

Минусы:

• Отсутствие строгой типизации "из коробки"
• Необходимость дополнительной настройки TypeScript для полной типобезопасности
• JSON-файлы переводов не типизированы автоматически

2. typesafe-i18n — строгая типизация

typesafe-i18n — библиотека, созданная специально для TypeScript. Её главная особенность — генерация типов на основе ваших файлов переводов.

Установка:

npm install typesafe-i18n

Настройка и пример:

// Создаём файл перевода: src/i18n/en/index.ts
export const en = {
  greeting: 'Hello {name}!',
  itemsCount: 'You have {count} item | You have {count} items',
} as const;

// Генерация типов (запускается автоматически)
// npx typesafe-i18n

// Использование в компоненте
import { i18n } from './i18n/i18n-util';

function Profile() {
  const LL = i18n();
  
  return (
    <div>
      <p>{LL.greeting({ name: 'Анна' })}</p>
      <p>{LL.itemsCount({ count: 5 })}</p>
    </div>
  );
}

Плюсы:

• Полная типобезопасность на всех этапах
• Автодополнение в IDE (IntelliSense)
• Валидация параметров во время компиляции
• Поддержка множественного числа и интерполяции

Минусы:

• Меньше сообщество и плагинов
• Требуется генерация типов при каждом изменении переводов
• Меньше гибкости для нестандартных сценариев

3. Lingui — экосистема с компиляцией

Lingui — современная библиотека, использующая компиляцию для оптимизации производительности. Она особенно популярна в React-приложениях.

Установка:

npm install @lingui/core @lingui/react @lingui/macro

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

import { Trans } from '@lingui/macro';
import { i18n } from '@ling