Система i18n

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

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

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

Vite — public/locales + react-i18next

Next.js — messages/ + next-intl

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

Конфигурация:
Все настройки сосредоточены в shared/config/i18n/. Каждый аспект (типы, инициализация, блоки) вынесен в отдельный файл.
Файлы переводов:
Vite: public/locales/[lng]/. Next.js: messages/[lng]/ (рекомендуется) или 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 через import type → TResources. Vite: public/locales; Next: messages/ (рекомендуется) или public/locales.

Vite — public/locales → i18n.config.ts

import type common from "../../../../public/locales/en/common.json";
import type header from "../../../../public/locales/en/header.json";
import type { TNestedKeyOf } from "./i18n.types";

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

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

export const NS = ["common", "header"] as const;
export type TCommonKeys = TNestedKeyOf<TCommon>;

Next.js — messages/ → i18n.config.ts

import type common from "../../../../messages/en/common.json";
import type header from "../../../../messages/en/header.json";
import type { TNestedKeyOf } from "./i18n.types";

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

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

export const NS = ["common", "header"] as const;
export type TCommonKeys = TNestedKeyOf<TCommon>;

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 (стек Vite SPA).

shared/config/i18n/i18n.init.ts

import i18n from "i18next";
import HttpBackend from "i18next-http-backend";
import { initReactI18next } from "react-i18next";
import { getNamespacePath } from "./i18n.blocks";
import { NS } from "./i18n.config";

i18n.use(HttpBackend)
    .use(initReactI18next)
    .init({
        fallbackLng: "en",
        ns: [...NS],
        defaultNS: NS[0],
        backend: {
            // без allowMultiLoading loadPath вызывается на каждую пару язык + namespace
            loadPath: (lngs: string[], nss: string[]) =>
                getNamespacePath(lngs[0], nss[0])
        }
    });
export default i18n;

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

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

shared/config/i18n/i18n.checker.ts

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

/** Ошибка компиляции, если T не never — в сообщении видны проблемные ключи */
type TAssertNoKeys<T extends never> = T;

// Нет ключа из EN или не совпал тип значения → ошибка
export const RU_TRANSLATION_CHECKER = {
    common: {} as typeof common_ru,
} satisfies TResources;

// satisfies не видит лишние ключи — проверяем обе стороны явно
export type TRuCommonMissingKeys = TAssertNoKeys<
    Exclude<TCommonKeys, TNestedKeyOf<typeof common_ru>>
>;
export type TRuCommonExtraKeys = TAssertNoKeys<
    Exclude<TNestedKeyOf<typeof common_ru>, TCommonKeys>
>;

07Использование в UI (выбери стек)

Одни typed namespaces — разный UI API и корень JSON. Vite SPA → react-i18next + public/locales. Next.js App Router → next-intl + messages.

Vite — react-i18next

Vite SPA: useTranslation + Trans. JSON: public/locales/[lng]/.

Vite — react-i18next + public/locales

import { useTranslation, Trans } from "react-i18next";

export const MyComponent = () => {
	const { t } = useTranslation("common");

	return (
		<div>
			<h1>{t("header.title")}</h1>
			<Trans
				ns="common"
				i18nKey="description.text"
				components={[<strong key="0" />, <br key="1" />]}
			/>
		</div>
	);
};

Next.js — next-intl

Next.js App Router: useTranslations + t.rich. JSON: messages/[lng]/ (рекомендуется) или public/locales/[lng]/ через import() в request.ts.

Next.js — next-intl + messages/

"use client";

import { useTranslations } from "next-intl";

export const MyComponent = () => {
	const t = useTranslations("common");

	return (
		<div>
			<h1>{t("header.title")}</h1>
			{t.rich("description.text", {
				strong: (chunks) => <strong>{chunks}</strong>,
				br: () => <br />
			})}
		</div>
	);
};

08Смена языка

Vite: changeLanguage + localStorage. Next.js: locale routing / next-intl navigation (не i18next.changeLanguage).

shared/config/i18n/change-language.ts

import i18n from "./i18n.init";

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