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.

i18n File Structure

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:
Located in public/locales/[lng]/. Use nested folders to 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, we import reference JSON files and create a master type 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;

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.

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;

06Consistency Control

Static check in i18n.checker.ts. Guarantees that all languages have an identical key structure.

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

07UI Usage

Parameterized useTranslation hook and the Trans component for working with dynamic content.

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

08Language Switching

The changeLanguage utility for synchronous library state and localStorage updates.

shared/config/i18n/change-language.ts

import i18n from "./i18n.init";

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