i18next for Internationalization

Applications often need to support multiple languages for their user interface.

frontendenforced by 1 rule

Context

Applications often need to support multiple languages for their user interface. A standardized approach to internationalization (i18n) is needed to translate all UI strings, persist language preferences across sessions, and ensure type-safe translation keys. For applications that need offline availability or fast startup, translations should be bundled with the application rather than loaded remotely, ensuring synchronous access.

The separation between Connected and Presentational components creates a natural boundary for i18n: Connected components handle translation lookups and pass translated strings to Presentational components as props, keeping Presentational components pure and testable without i18n dependencies.

Decision

Use i18next with react-i18next as the internationalization library for the frontend.

Bundled translations: JSON translation files are statically imported (no HTTP backend), ensuring synchronous availability.
Type-safe translation keys: Use CustomTypeOptions augmentation to provide type-safe t() keys.
Connected/Presentational pattern: Connected components call useTranslation() and build typed labels objects that are passed to Presentational components via a labels prop.
No hardcoded strings: Presentational components must not contain hardcoded user-facing strings in JSX; all text comes through the labels prop.
Single namespace: All strings live in one translation namespace per language under src/i18n/locales/{lang}/translation.json.
Pluralization: Use _one/_other key suffixes with the count parameter.
Interpolation: Use {{variable}} syntax for dynamic values.
Presentational pluralization: Pass pluralized strings as function props (e.g., formatCount: (count: number) => string) from Connected components.

Do's and Don'ts

Do

Call useTranslation() only in Connected components.
Pass all translated strings as typed labels props to Presentational components.
Use factory functions for validation schemas that need translated messages.
Use i18n.t() (direct import) for code outside React components (utilities, module-level).
Use _one/_other key suffixes for pluralization.
Add new translation keys to all language files simultaneously.
Provide English literal strings in Storybook story labels args.

Don't

Call useTranslation() in Presentational components.
Hardcode user-facing strings in Presentational component JSX.
Use t() at module scope in non-factory contexts (translations may not be initialized).
Create multiple namespaces; use the single translation namespace.
Use HTTP backends for loading translations; bundle them statically.
Introduce alternative i18n libraries (react-intl, lingui, etc.).

Consequences

Positive

Full type safety for translation keys via TypeScript augmentation.
Synchronous initialization with no loading states needed for translations.
Clean separation: translations flow through the Connected/Presentational boundary via typed labels props.
Persistent language preference via localStorage survives app restarts.
Bundled translations work reliably offline.

Negative

Connected components become more verbose, building complete labels objects for each Presentational child.
All language files must be kept in sync when adding new translation keys.
Factory function overhead for schemas and module-level constants that reference translations.

Enforcement rules

adrs/FE-001-i18next.rules.ts

/// <reference path="../rules.d.ts" />

export default {
  rules: {
    "i18next-in-deps": {
      description: "i18next and react-i18next must be listed in frontend dependencies",
      async check(ctx) {
        let pkg: {
          dependencies?: Record<string, string>;
          devDependencies?: Record<string, string>;
        };
        try {
          pkg = (await ctx.readJSON("packages/frontend/package.json")) as typeof pkg;
        } catch {
          // No frontend package.json found — skip
          return;
        }

        const allDeps = {
          ...pkg.dependencies,
          ...pkg.devDependencies,
        };

        if (!allDeps["i18next"]) {
          ctx.report.violation({
            message: "packages/frontend/package.json: Missing i18next in dependencies",
            file: "packages/frontend/package.json",
            fix: "Add i18next to dependencies",
          });
        }

        if (!allDeps["react-i18next"]) {
          ctx.report.violation({
            message: "packages/frontend/package.json: Missing react-i18next in dependencies",
            file: "packages/frontend/package.json",
            fix: "Add react-i18next to dependencies",
          });
        }
      },
    },

    "translation-key-consistency": {
      description:
        "All translation JSON files must have identical key structures across supported languages",
      async check(ctx) {
        const translationFiles = ctx.scopedFiles.filter((f) =>
          /[\\/]src[\\/]i18n[\\/]locales[\\/][^\\/]+[\\/]translation\.json$/.test(f),
        );

        if (translationFiles.length < 2) {
          // Nothing to compare if there's fewer than two languages
          return;
        }

        function extractKeys(obj: Record<string, unknown>, prefix = ""): Set<string> {
          const keys = new Set<string>();
          for (const [key, value] of Object.entries(obj)) {
            const fullKey = prefix ? `${prefix}.${key}` : key;
            if (typeof value === "object" && value !== null && !Array.isArray(value)) {
              for (const subKey of extractKeys(value as Record<string, unknown>, fullKey)) {
                keys.add(subKey);
              }
            } else {
              keys.add(fullKey);
            }
          }
          return keys;
        }

        function langFromPath(path: string): string {
          const match = path.match(/locales[\\/]([^\\/]+)[\\/]translation\.json$/);
          return match ? match[1] : path;
        }

        const langKeys = new Map<string, Set<string>>();
        const langPaths = new Map<string, string>();

        const langResults = await Promise.all(
          translationFiles.map(async (filePath) => {
            const lang = langFromPath(filePath);
            try {
              const content = await ctx.readFile(filePath);
              const json = JSON.parse(content) as Record<string, unknown>;
              return { lang, filePath, keys: extractKeys(json), error: false };
            } catch {
              return { lang, filePath, keys: new Set<string>(), error: true };
            }
          }),
        );

        for (const result of langResults) {
          if (result.error) {
            ctx.report.violation({
              message: `${result.filePath}: Could not read or parse translation file for "${result.lang}"`,
              file: result.filePath,
              fix: `Ensure ${result.filePath} exists and contains valid JSON`,
            });
            return;
          }
          langPaths.set(result.lang, result.filePath);
          langKeys.set(result.lang, result.keys);
        }

        // Build union of all keys
        const allKeys = new Set<string>();
        for (const keys of langKeys.values()) {
          for (const key of keys) {
            allKeys.add(key);
          }
        }

        // Check each key exists in all languages
        for (const key of allKeys) {
          const missingLangs: string[] = [];
          for (const [lang, keys] of langKeys) {
            if (!keys.has(key)) {
              missingLangs.push(lang);
            }
          }

          if (missingLangs.length > 0) {
            const presentLangs = [...langKeys.entries()]
              .filter(([, keys]) => keys.has(key))
              .map(([lang]) => lang);

            const firstMissingLang = [...langKeys.entries()].find(([, keys]) => !keys.has(key));
            const file = firstMissingLang
              ? (langPaths.get(firstMissingLang[0]) ?? translationFiles[0])
              : translationFiles[0];

            ctx.report.violation({
              message: `Translation key "${key}" exists in ${presentLangs.join(", ")} but is missing from ${missingLangs.join(", ")}`,
              file,
              fix: `Add the key "${key}" to the missing translation file(s)`,
            });
          }
        }
      },
    },
  },
} satisfies RuleSet;