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

• Перевести личный кабинет пользователя на русский и английский (в перспективе и на другие языки).

• При этом, определять язык пользователя при первом заходе в ЛК и давать его изменить.

• Запоминать выбранный язык при перезагрузке страницы.

• Сделать так, чтобы в проектах была типизация файлов с переводами (чтобы нельзя было забыть добавить один из языков).

Как я это делал — расскажу в статье.

Содержание

• Первоначальное решение

• Выбор библиотеки переводов

• Создаём шаблон проекта

• Добавляем локализацию
  

  • Создаём переводы

  • Добавляем типы переводов в проект

  • Инициализируем i18next

  • Добавляем выбор языка

  • Проброс языка в API

• Итоговая страница

• Заключение

Первоначальное решение

Сначала я решил задачу, просто закинув все переводы в несколько .ts-файлов с общим интерфейсом и выбирая язык через Redux. Всё работало, но было ощущение, что это я переизобрел велосипед.

Хотелось чего-то более стандартного и популярного на рынке: по-любому эту задачу кто-то уже решил более качественно. Да и всё-таки онбординг новых разработчиков никто не отменял. Поэтому было принято решение: выбрать популярную библиотеку и перенести переводы на неё.

Выбор библиотеки переводов

Для решения задачи я выбрал i18next.

Почему именно i18next?

• Имеет поддержку типизации "из коробки" (дружит TS типы и даже кое-как с автокомплишном).

• "Дружит" с React Server Component в Next.js (для Next.js 13+).

• Поддерживает lazy loading (разделение переводов по чанкам/файлам) для ускорения страниц.

• Всё выше делается просто относительной других популярных библиотек.

Глобально, сейчас из этого всего в проекте нужна только типизация. Но закладываю серверные компоненты и разделение кода на будущее. Проект планирует расширять, и эти возможности пригодятся для SEO.

Для наглядности сделал таблицу, где сравнил три самые популярные библиотеки:

*оценка может быть субъективной из расчёта на конкретный проект, на объективность не претендую.

*i18n - расшифровывается как "internationalization".

Минутка самопиара

У меня есть Telegram-канал, где я собираю ссылки на свои статьи про Full-Stack разработку, развитие SaaS-продуктов и управление IT-проектами.

Создаём шаблон проекта

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

Для начала создадим новый проект на Next.js с TypeScript шаблоном.

Выполняем команды:

npx create-next-app@latest my-multilang-app --typescript

Я сразу добавил ESLint, TailwindCSS и Turbopack:

Появляется структура:

my-multilang-app/
├─ app/
│   ├─ page.tsx 
│   └─ ...
├─ public/
├─ ...
└─ package.json

И сразу добавляем библиотеки i18next:

npm install i18next react-i18next i18next-browser-languagedetector

react-i18next — адаптер для React.
i18next-browser-languagedetector — плагин для определения языка в браузере.

Добавляем локализацию

Создаём переводы

Создаём тип переводов и сами переводы в папке i18n:

i18n/
├─ translations/en_translation.json
├─ translations/ru_translation.json
├─ translations/TranslationTypes.ts
└─ i18n.ts

Разумеется, можно назвать файлы и папки по-другому, главное, чтобы была понятная структура. Я выбрал нейминг, стандартный для Feature Sliced Design (но FSD мы здесь не используем).

Далее сами файлы:

i18n/translations/TranslationTypes.ts

export interface TranslationTypes {
  // Используем схему componentName.field
  page: {
    hello: string;
    changeLanguage: string;
    dashboardTitle: string;
    profile: string;
  };
}

i18n/translations/en_translation.json

{
  "page": {
    "hello": "Hello, {{name}}!",
    "changeLanguage": "Change language to Russian",
    "dashboardTitle": "User Dashboard",
    "profile": "My profile"
  }
}

i18n/translations/ru_translation.json

{
  "page": {
    "hello": "Привет, {{name}}!",
    "changeLanguage": "Переключить язык на английский",
    "dashboardTitle": "Личный кабинет",
    "profile": "Мой профиль"
  }
}

Добавляем типы переводов в проект

Чтобы включить типизацию, нужно воспользоваться встроенным механизмом декларации типов i18next. Создадим файл resources.d.ts (или i18n.d.ts) в корне проекта или в папке types, где пропишем:

import "i18next";
import { TranslationTypes } from "@/i18n/translations/TranslationTypes";

declare module "i18next" {
  interface CustomTypeOptions {
    resources: TranslationTypes;
  }
}

Теперь при использовании useTranslation и t в нашем коде TypeScript будет подсказывать, какие ключи перевода у нас существуют.

Инициализируем i18next

Добавим файл i18n.ts в папку /i18n:

import i18n from "i18next";
import LanguageDetector from "i18next-browser-languagedetector";
import { initReactI18next } from "react-i18next";

import { TranslationTypes } from "./translations/TranslationTypes";
import en from "./translations/en_translation.json";
import ru from "./translations/ru_translation.json";

// Если забудем добавить поле в один из языков,
// здесь появится TypeScript ошибка
const resources: Record<string, { translation: TranslationTypes }> = {
  en: { translation: en },
  ru: { translation: ru },
};

i18n
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    resources,
    detection: {
      order: ["localStorage", "navigator"],
      caches: ["localStorage"],
      lookupLocalStorage: "i18nextLng",
    },
    fallbackLng: "en",
    interpolation: {
      escapeValue: false,
    },
  });

export default i18n;

Обратите внимание, что i18next-browser-languagedetector смотрит, какой язык установлен в браузере, а также может работать с cookie/localStorage. Это решает задачу "запоминать язык при перезагрузке страницы".

Здесь мы указываем логику, в которой сначала пытаемся брать язык из localStorage, а затем из браузера:

order: ["localStorage", "navigator"],

i18next умеет сам выбирать нужный язык в зависимости от настройки браузера (ru, en, sp и другие). Нам нужно только указать нужный файл для языка:

const resources: Record<string, { translation: TranslationTypes }> = {
  en: { translation: en },
  ru: { translation: ru },
};

...
...
    // Если нужного языка нет, берём английский
    fallbackLng: "en",
    ...
...

Добавляем выбор языка

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

LanguageSwitcher.tsx:

"use client";

import { useTranslation } from "react-i18next";

export default function LanguageSwitcher() {
  const { i18n } = useTranslation();

  const changeLanguage = async (lang: "en" | "ru") => {
    await i18n.changeLanguage(lang);
  };

  return (
    <div className="mt-4 space-x-2">
      <button
        onClick={() => changeLanguage("en")}
        className="px-4 py-2 text-sm font-medium text-gray-700 bg-white border border-gray-300 rounded-md hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500"
      >
        EN
      </button>

      <button
        onClick={() => changeLanguage("ru")}
        className="px-4 py-2 text-sm font-medium text-gray-700 bg-white border border-gray-300 rounded-md hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500"
      >
        RU
      </button>
    </div>
  );
}

Теперь мы можем переиспользовать этот компонент на любой странице или в header'e.

Проброс языка в API

Если у вас локализация распространяется и на API, вам нужно прокидывать язык в запросы. Его можно брать из нашего файла i18n и добавлять в заголовок. Например, в fetch-запросе:

await fetch('/api/user', {
  headers: {
    'Authorization': getAccessToken(),
    'Accept-Language': i18n.language, // берем текущий язык
  }
});

Итоговая страница

Полный пример страницы с переводами выглядит вот так:

app/page.tsx

"use client";

import LanguageSwitcher from "@/components/LanguageSwitcher";
import { useTranslation } from "react-i18next";
import "../i18n/i18n";

export default function HomePage() {
  const { t } = useTranslation();

  return (
    <main className="p-8 max-w-4xl mx-auto">
      <h1 className="text-3xl font-bold text-gray-900 mb-6">
        {t("page.dashboardTitle")}
      </h1>

      <div className="space-y-4">
        <p className="text-lg text-gray-700">
          {t("page.hello", { name: "John" })}
        </p>
        <p className="text-lg text-gray-700">{t("page.profile")}</p>
      </div>

      {/* Кнопка для переключения языка */}
      <div className="mt-8">
        <LanguageSwitcher />
      </div>
    </main>
  );
}

Как результат смены языка в LanguageSwitcher будут меняться все надписи, а при перезагрузке страницы сохранится последний выбранный язык:

Конкретно в этом примере мы используем "use client" для упрощения. В следующей статье я покажу, как использовать i18next с SSR'ом.

Заключение

Итого, при смене языка у нас меняются все тексты на странице:

• Заголовок «Личный кабинет» <> «User Dashboard»

• Приветствие «Привет, John!» <> «Hello, John!»

• Кнопка для профиля «Мой профиль» <> «My profile»

А при перезагрузке приложения язык остаётся выбранным, так как i18next-browser-languagedetector сохраняет язык в localStorage'e.

Чтобы добавить новые языки (испанский, китайский и т.д.) нужно расширить ресурс в i18n.ts и добавить новые файлы с переводами (например, es_translation.json, zh_translation.json). Типизация подскажет, не забыли ли мы какие-то поля.

P.S. Напомню, что у меня есть Telegram-канал, где я собираю ссылки на свои статьи про Full-Stack разработку, развитие SaaS-продуктов и управление IT-проектами.

Если остались вопросы, пишите в комментариях!