I18nProvider

React Context Provider with cookie-based language persistence and SSR support

Overview

I18nProvideris a root component that provides internationalization context to the entire application. It manages language state, handles cookie persistence, and ensures zero hydration mismatches in SSR.

✓Cookie-based language persistence

✓Zero hydration mismatches in Next.js

✓Type-safe language management

✓Auto language detection from cookies

API Reference

Props

initialLanguageString (Required)

The initial language code to use. Must match one of the keys in the translations object.

"initialLanguage="ko"

translationsObject (Required)

An object containing translation keys and values for all supported languages.

translations={{
  en: { "Welcome": "Welcome" },
  ko: { "Welcome": "환영합니다" }
}}

childrenReactNode (Required)

Application components that need to access translations.

languageManagerOptionsObject (Optional)

Additional configuration for language management.

languageManagerOptions={{
  defaultLanguage: "ko",
  availableLanguages: [
    { code: "ko", name: "한국어", flag: "🇰🇷" },
    { code: "en", name: "English", flag: "🇺🇸" }
  ]
}}

Usage Examples

Basic Setup (Client Components Only)

// app/layout.tsx
import { I18nProvider } from "i18nexus";
import { translations } from "@/lib/i18n";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <I18nProvider 
          initialLanguage="ko" 
          translations={translations}
        >
          {children}
        </I18nProvider>
      </body>
    </html>
  );
}

Server-Side Rendering (Next.js App Router)

// app/layout.tsx
import { I18nProvider } from "i18nexus";
import { getServerLanguage } from "i18nexus/server";
import { headers } from "next/headers";
import { translations } from "@/lib/i18n";

export default async function RootLayout({ children }) {
  // Read language from cookie on server
  const headersList = await headers();
  const language = getServerLanguage(headersList);

  return (
    <html lang={language}>
      <body>
        <I18nProvider 
          initialLanguage={language} 
          translations={translations}
        >
          {children}
        </I18nProvider>
      </body>
    </html>
  );
}

💡 Why It Matters: By reading the language from cookies on the server, we ensure the initial HTML matches what the client expects, preventing hydration mismatches.

Advanced Settings

// app/layout.tsx
import { I18nProvider } from "i18nexus";
import { translations } from "@/lib/i18n";

const languageManagerOptions = {
  defaultLanguage: "ko",
  availableLanguages: [
    { code: "ko", name: "한국어", flag: "🇰🇷" },
    { code: "en", name: "English", flag: "🇺🇸" },
    { code: "ja", name: "日本語", flag: "🇯🇵" },
  ],
  cookieOptions: {
    maxAge: 365 * 24 * 60 * 60, // 1 year
    path: "/",
    sameSite: "lax",
  }
};

export default function RootLayout({ children }) {
  return (
    <I18nProvider 
      initialLanguage="ko" 
      translations={translations}
      languageManagerOptions={languageManagerOptions}
    >
      {children}
    </I18nProvider>
  );
}

Best Practices

✅Recommended: Place at the root of your app

Always wrap your entire application with I18nProvider at the root layout level so all components can access translations.

✅Recommended: Use server-side language detection

For Next.js applications, always read the language from cookies on the server to prevent hydration mismatches.

❌Don't: Nest multiple providers

Don't nest I18nProvider components. Use only one provider at the root level.

❌Don't: Dynamically change initialLanguage

The initialLanguage prop should only be set once. To dynamically change the language, use changeLanguage() from useLanguageSwitcher.