i18n Best Practices 2026: The Complete Guide

// i18n.config.ts — Configure AI translation with Better i18n
export default defineConfig({
  project: "my-org/my-app",
  sourceLanguage: "en",
  targetLanguages: ["es", "fr", "de", "ja", "ko", "zh"],
  ai: {
    enabled: true,
    // Custom instructions improve AI output quality
    instructions: `
      - Use informal "tu" form for Spanish
      - Keep technical terms in English for Japanese
      - Match the playful, developer-friendly tone of our brand
    `,
    // Auto-translate new keys on push
    autoTranslate: true,
    // Require human review before publishing
    requireReview: true,
  },
});

// eslint.config.ts — Add i18n linting rules
import i18nPlugin from "eslint-plugin-i18n-json";

export default [
  {
    plugins: { "i18n-json": i18nPlugin },
    rules: {
      // Detect hardcoded strings in JSX
      "i18n-json/no-hardcoded-strings": "error",
      // Ensure all keys have translations
      "i18n-json/valid-message-syntax": "error",
      // Check ICU MessageFormat syntax
      "i18n-json/valid-icu-syntax": "error",
    },
  },
];

# CLI-based static analysis with Better i18n
bunx @better-i18n/cli lint

# Output:
# src/components/Header.tsx:15 — Hardcoded string "Welcome back"
# src/pages/pricing.tsx:42 — Missing key "pricing.enterprise.cta" in: es, fr, de
# locales/en.json — Unused keys: 12 (run `cli prune` to remove)

# .github/workflows/i18n.yml
name: i18n Pipeline
on:
  pull_request:
    paths:
      - "src/**"
      - "locales/**"

jobs:
  i18n-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check translation coverage
        run: bunx @better-i18n/cli coverage --min 95
        # Fails if any language drops below 95% coverage

      - name: Lint i18n keys
        run: bunx @better-i18n/cli lint --strict
        # Checks for hardcoded strings, unused keys, syntax errors

      - name: Sync new keys
        run: bunx @better-i18n/cli push --dry-run
        # Shows what keys would be synced (no side effects)

      - name: Validate translations
        run: bunx @better-i18n/cli validate
        # Checks ICU syntax, placeholder consistency, length limits

{
  "auth.login.title": "Sign in to your account",
  "auth.login.email.label": "Email address",
  "auth.login.email.placeholder": "you@example.com",
  "auth.login.email.error.required": "Email is required",
  "auth.login.email.error.invalid": "Please enter a valid email",
  "auth.login.submit": "Sign in",
  "auth.login.forgot_password": "Forgot your password?",

  "dashboard.header.greeting": "Welcome back, {name}",
  "dashboard.projects.empty.title": "No projects yet",
  "dashboard.projects.empty.description": "Create your first project to get started",
  "dashboard.projects.empty.cta": "Create project",

  "common.actions.save": "Save",
  "common.actions.cancel": "Cancel",
  "common.actions.delete": "Delete",
  "common.actions.confirm": "Are you sure?",
  "common.errors.generic": "Something went wrong. Please try again.",
  "common.errors.network": "Network error. Check your connection."
}

{
  "Welcome back": "Welcome back",
  "btn1": "Save",
  "page_title": "Dashboard",
  "err_msg": "Something went wrong",
  "auth_login_email_address_input_field_label_text": "Email"
}

{
  "inbox.message_count": "{count, plural, =0 {No messages} one {# message} other {# messages}}",

  "cart.item_count": "{count, plural, =0 {Your cart is empty} one {# item in cart} other {# items in cart}}",

  "project.member_count": "{count, plural, =0 {No members} one {# member} other {# members}}"
}

{
  "activity.comment": "{gender, select, female {{count, plural, one {She left # comment} other {She left # comments}}} male {{count, plural, one {He left # comment} other {He left # comments}}} other {{count, plural, one {They left # comment} other {They left # comments}}}}"
}

import { useTranslations } from "@better-i18n/use-intl";

function InboxHeader({ messageCount }: { messageCount: number }) {
  const t = useTranslations("inbox");

  return (
    <h2>{t("message_count", { count: messageCount })}</h2>
  );
  // count=0 -> "No messages"
  // count=1 -> "1 message"
  // count=5 -> "5 messages"
}

/* Physical properties (breaks RTL) */
.card {
  margin-left: 16px;
  padding-right: 24px;
  text-align: left;
  border-left: 2px solid blue;
}

/* Logical properties (works in both LTR and RTL) */
.card {
  margin-inline-start: 16px;
  padding-inline-end: 24px;
  text-align: start;
  border-inline-start: 2px solid blue;
}

function NavigationArrow({ direction }: { direction: "back" | "forward" }) {
  return (
    <button className="flex items-center gap-2">
      {/* Tailwind v4 logical utilities */}
      <ChevronIcon className="rtl:rotate-180" />
      <span className="ms-2">{/* margin-inline-start */}</span>
    </button>
  );
}

// In your root layout
function RootLayout({ locale }: { locale: string }) {
  const direction = ["ar", "he", "fa", "ur"].includes(locale) ? "rtl" : "ltr";

  return (
    <html lang={locale} dir={direction}>
      <body>{/* content */}</body>
    </html>
  );
}

// Use Intl.DateTimeFormat — never hardcode date patterns
function formatDate(date: Date, locale: string): string {
  return new Intl.DateTimeFormat(locale, {
    year: "numeric",
    month: "long",
    day: "numeric",
  }).format(date);
}

formatDate(new Date("2026-03-15"), "en-US");  // "March 15, 2026"
formatDate(new Date("2026-03-15"), "de-DE");  // "15. Marz 2026"
formatDate(new Date("2026-03-15"), "ja-JP");  // "2026年3月15日"

function formatRelativeTime(date: Date, locale: string): string {
  const rtf = new Intl.RelativeTimeFormat(locale, { numeric: "auto" });
  const diffMs = date.getTime() - Date.now();
  const diffDays = Math.round(diffMs / (1000 * 60 * 60 * 24));

  if (Math.abs(diffDays) < 1) return rtf.format(0, "day"); // "today"
  if (Math.abs(diffDays) < 7) return rtf.format(diffDays, "day");
  if (Math.abs(diffDays) < 30) return rtf.format(Math.round(diffDays / 7), "week");
  return rtf.format(Math.round(diffDays / 30), "month");
}

formatRelativeTime(yesterday, "en");  // "yesterday"
formatRelativeTime(yesterday, "de");  // "gestern"
formatRelativeTime(yesterday, "ja");  // "昨日"

// Numbers
new Intl.NumberFormat("en-US").format(1234567.89);  // "1,234,567.89"
new Intl.NumberFormat("de-DE").format(1234567.89);  // "1.234.567,89"
new Intl.NumberFormat("ja-JP").format(1234567.89);  // "1,234,567.89"

// Currency
new Intl.NumberFormat("en-US", {
  style: "currency",
  currency: "USD",
}).format(29.99);  // "$29.99"

new Intl.NumberFormat("de-DE", {
  style: "currency",
  currency: "EUR",
}).format(29.99);  // "29,99 EUR"

new Intl.NumberFormat("ja-JP", {
  style: "currency",
  currency: "JPY",
}).format(3000);  // "3,000 JPY"

// Compact notation for large numbers
new Intl.NumberFormat("en", { notation: "compact" }).format(1500000);  // "1.5M"
new Intl.NumberFormat("de", { notation: "compact" }).format(1500000);  // "1,5 Mio."
new Intl.NumberFormat("ja", { notation: "compact" }).format(1500000);  // "150万"

        /  Visual  \         — Screenshot regression tests
       /  (5-10)    \        — Key user flows per language
      /---------------\
     / Integration     \    — Component rendering with all locales
    /   (50-100)        \   — Layout overflow detection
   /---------------------\
  /     Unit Tests        \ — ICU syntax validation
 /      (200-500)          \— Key coverage checks
/---------------------------\— Placeholder consistency

import { describe, it, expect } from "vitest";
import en from "../locales/en.json";
import es from "../locales/es.json";
import de from "../locales/de.json";

const sourceKeys = Object.keys(flattenKeys(en));
const targetLocales = { es, de };

describe("Translation coverage", () => {
  for (const [locale, translations] of Object.entries(targetLocales)) {
    it(`${locale} has all keys from source`, () => {
      const targetKeys = Object.keys(flattenKeys(translations));
      const missingKeys = sourceKeys.filter((k) => !targetKeys.includes(k));

      expect(missingKeys).toEqual([]);
    });
  }
});

describe("ICU syntax validation", () => {
  it("all translations have valid ICU MessageFormat", () => {
    for (const [key, value] of Object.entries(flattenKeys(en))) {
      expect(() => new IntlMessageFormat(value, "en")).not.toThrow();
    }
  });
});

import { render, screen } from "@testing-library/react";
import { IntlProvider } from "@better-i18n/use-intl";

const LOCALES_TO_TEST = ["en", "de", "ja", "ar"];

describe.each(LOCALES_TO_TEST)("Button layout in %s", (locale) => {
  it("navigation buttons do not overflow container", async () => {
    const messages = await loadMessages(locale);

    const { container } = render(
      <IntlProvider locale={locale} messages={messages}>
        <Navigation />
      </IntlProvider>
    );

    const nav = container.querySelector("nav");
    expect(nav!.scrollWidth).toBeLessThanOrEqual(nav!.clientWidth);
  });
});

// Pseudo-locale transforms
function pseudoLocalize(text: string): string {
  // Accent characters to simulate diacritics
  const accents: Record<string, string> = {
    a: "a", e: "e", i: "i", o: "o", u: "u",
    A: "A", E: "E", I: "I", O: "O", U: "U",
  };

  // Add 40% length expansion (German/Finnish are ~30-40% longer)
  const expanded = text.replace(/[aeiouAEIOU]/g, (c) => accents[c] || c);
  const padding = "~".repeat(Math.ceil(text.length * 0.4));

  return `[${expanded}${padding}]`;
}

// "Save changes" -> "[Save changes~~~~~~~~]"
// Immediately reveals: truncation, overflow, hardcoded strings

// Load translations per route + locale
// Only load the namespaces needed for the current page

import { createRoute } from "@tanstack/react-router";

export const dashboardRoute = createRoute({
  path: "/dashboard",
  loader: async ({ params }) => {
    const locale = params.locale || "en";

    // Load only dashboard namespace translations
    const messages = await import(`../locales/${locale}/dashboard.json`);

    return { messages: messages.default, locale };
  },
  component: DashboardPage,
});

// locales/en/common.json — loaded on every page (~2KB)
{
  "common.nav.home": "Home",
  "common.nav.dashboard": "Dashboard",
  "common.actions.save": "Save"
}

// locales/en/dashboard.json — loaded only on dashboard (~5KB)
{
  "dashboard.title": "Dashboard",
  "dashboard.stats.users": "Active users"
}

// locales/en/settings.json — loaded only on settings (~3KB)
{
  "settings.title": "Settings",
  "settings.profile.name": "Display name"
}

// Better i18n loads translations from edge CDN
// with automatic locale-based splitting

import { createBetterI18n } from "@better-i18n/core";

const i18n = createBetterI18n({
  project: "my-org/my-app",
  // Only fetches the active locale
  // Caches with TTL for instant subsequent loads
  // Supports namespace-level granularity
  cdn: {
    enabled: true,
    ttl: 300, // 5 minutes cache
  },
});

// First load: fetches from CDN (~50ms from edge)
// Subsequent loads: served from memory cache (~0ms)
const messages = await i18n.getMessages("en", ["common", "dashboard"]);

// Preload likely locale switches based on user behavior
function useLocalePreloader(currentLocale: string) {
  useEffect(() => {
    // Preload browser's preferred language if different
    const browserLocale = navigator.language.split("-")[0];
    if (browserLocale !== currentLocale) {
      i18n.preload(browserLocale, ["common"]);
    }

    // Preload on hover over language switcher
    const switcher = document.querySelector("[data-locale-switcher]");
    switcher?.addEventListener("mouseenter", () => {
      const targetLocale = switcher.getAttribute("data-target-locale");
      if (targetLocale) {
        i18n.preload(targetLocale, ["common"]);
      }
    });
  }, [currentLocale]);
}

// Use feature flags to control locale availability
const LOCALE_ROLLOUT = {
  en: { enabled: true, percentage: 100 },
  es: { enabled: true, percentage: 100 },
  fr: { enabled: true, percentage: 100 },
  de: { enabled: true, percentage: 50 },  // 50% rollout
  ja: { enabled: true, percentage: 25 },  // 25% rollout
  ko: { enabled: false, percentage: 0 },  // Not yet launched
} as const;

function getAvailableLocale(
  requestedLocale: string,
  userId: string
): string {
  const config = LOCALE_ROLLOUT[requestedLocale as keyof typeof LOCALE_ROLLOUT];

  if (!config?.enabled) return "en";

  // Consistent user bucketing for gradual rollout
  const bucket = hashUserId(userId) % 100;
  if (bucket >= config.percentage) return "en";

  return requestedLocale;
}