i18n System

Comprehensive guide to internationalization architecture. Includes automatic key typing, translation completeness checks, and dynamic resource loading.

i18n Architecture Patterns

Benefit: Total type safety — the project will not compile if a key is missing or translation structures differ across languages.

Vite — public/locales + react-i18next

Next.js — messages/ + next-intl

Naming and Location Conventions

Configuration:
All settings are centralized in shared/config/i18n/. Each aspect (types, initialization, blocks) is separated into its own file.
Translation Files:
Vite: public/locales/[lng]/. Next.js: messages/[lng]/ (recommended) or public/locales/[lng]/. Nested folders group namespaces (e.g., booking/order.json).

01i18nKey Wrapper

Identity function for typing string keys. Provides IDE autocompletion for a specific Namespace.

shared/config/i18n/i18n-key.ts

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

02Type Magic

Recursive JSON object traversal via TNestedKeyOf to generate dot-notated key paths.

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];

03Resource Registry

In i18n.config.ts, import reference JSON via import type and build TResources. Vite: public/locales; Next: messages/ (recommended) or 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>;

04Translation Blocks

Configuring physical file locations and dynamic chunk loading in 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`;
};

05i18next Initialization

Binding plugins and configuration into a single library instance in i18n.init.ts (Vite SPA stack).

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;

06Consistency Control

Static check in i18n.checker.ts: satisfies catches missing keys, an explicit TNestedKeyOf check catches extra keys. Guarantees that all languages have an identical key structure.

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>
>;

07UI Usage (pick your stack)

Same typed namespaces — different UI APIs and JSON roots. 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]/ (recommended) or public/locales/[lng]/ loaded via import() in 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>
	);
};

08Language Switching

Vite: changeLanguage + localStorage. Next.js: locale routing / next-intl navigation (not 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);
};