Система i18n

Руководство по архитектуре интернационализации. Включает автоматическую типизацию ключей, проверку полноты перевода и динамическую загрузку ресурсов.

Шаблоны архитектуры i18n

Преимущество: Полная типобезопасность — при отсутствии ключа или несовпадении структуры перевода в разных языках проект не скомпилируется.

Структура файлов i18n

Соглашения и расположение

Конфигурация:
Все настройки сосредоточены в shared/config/i18n/. Каждый аспект (типы, инициализация, блоки) вынесен в отдельный файл.
Файлы переводов:
Располагаются в public/locales/[lng]/. Используйте вложенные папки для группировки namespaces (например, booking/order.json).

01Обертка i18nKey

Identity function для типизации строковых ключей. Обеспечивает автодополнение в IDE для конкретного Namespace.

shared/config/i18n/i18n-key.ts

export const i18nKey =
    <Keys extends string>() =>
    <K extends Keys>(key: K) =>
        key;

02Магия типов

Рекурсивный обход JSON-объектов через TNestedKeyOf для генерации путей к ключам через точку.

shared/config/i18n/i18n.types.ts

export type TDotPrefix<T extends string, P extends string> = P extends ""
    ? T
    : `${P}.${T}`;

export type TNestedKeyOf<ObjectType extends object> = {
    [Key in keyof ObjectType & string]: ObjectType[Key] extends object
        ? TDotPrefix<TNestedKeyOf<ObjectType[Key]>, Key>
        : Key;
}[keyof ObjectType & string];

03Реестр ресурсов

В i18n.config.ts импортируем эталонные JSON-файлы и создаем мастер-тип TResources.

shared/config/i18n/i18n.config.ts

import common from "../../../../public/locales/en/common.json";
import header from "../../../../public/locales/en/header.json";

export type TCommon = typeof common;
export type THeader = typeof header;

export type TResources = {
    common: TCommon;
    header: THeader;
};

export const NS = ["common", "header"] as const;

04Группировка блоков

Настраиваем физическое расположение файлов и динамическую подгрузку чанков в i18n.blocks.ts.

shared/config/i18n/i18n.blocks.ts

export const TRANSLATION_BLOCKS = {
    booking: { folder: "booking", namespaces: ["orders_page"] },
    shared: { folder: "", namespaces: ["header", "common"] }
};

export const getNamespacePath = (lng: string, ns: string): string => {
    // ... логика определения пути к JSON
    return `/locales/${lng}/${ns}.json`;
};

05Инициализация i18next

Связываем плагины и конфигурацию в единый экземпляр библиотеки в i18n.init.ts.

shared/config/i18n/i18n.init.ts

import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import { NS } from "./i18n.config";

i18n.use(initReactI18next).init({
    fallbackLng: "en",
    ns: NS,
    backend: {
        loadPath: (lngs, nss) => getNamespacePath(lngs[0], nss[0])
    }
});
export default i18n;

06Контроль консистентности

Статическая проверка в i18n.checker.ts. Гарантирует, что все языки имеют идентичную структуру ключей.

shared/config/i18n/i18n.checker.ts

import type { TResources } from "./i18n.config";
import common_ru from "../../../../public/locales/ru/common.json";

// Статическая проверка: если в RU нет ключа из EN - будет ошибка
export const RU_TRANSLATION_CHECKER: TResources = {
    common: common_ru,
};

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

Параметризованный хук useTranslation и компонент Trans для работы с динамическим контентом.

components/Example.tsx

import { useTranslations } from "next-intl";

export const MyComponent = () => {
    const t = useTranslations("common");
    
    return <h1>{t("header.title")}</h1>;
};

components/TransExample.tsx

import { useTranslations } from "next-intl";

export const MyComponent = () => {
    const t = useTranslations("common");
    
    return (
        <div>
            <h1>{t("header.title")}</h1>
            {t.rich("description.text", {
								0: (chunks) => <strong>{chunks}</strong/>,
								1: (chunks) => <br>{chunks}</br/>,
							})}
        </div>
    );
};

08Смена языка

Утилита changeLanguage для синхронного обновления состояния библиотеки и localStorage.

shared/config/i18n/change-language.ts

import i18n from "./i18n.init";

export const changeLanguage = (lng: string) => {
    i18n.changeLanguage(lng);
    localStorage.setItem("i18nextLng", lng);
};