홈/i18nexus/I18nProvider

I18nProvider

쿠키 기반 언어 영속성 및 SSR 지원을 갖춘 React Context Provider

개요

I18nProvider는 전체 애플리케이션에 국제화 컨텍스트를 제공하는 루트 컴포넌트입니다. 언어 상태를 관리하고, 쿠키 영속성을 처리하며, SSR에서 하이드레이션 불일치가 없음을 보장합니다.

✓쿠키 기반 언어 영속성

✓Next.js에서 하이드레이션 불일치 제로

✓타입 안전 언어 관리

✓쿠키에서 자동 언어 감지

API 레퍼런스

Props

initialLanguage문자열 (필수)

사용할 초기 언어 코드입니다. translations 객체의 키 중 하나와 일치해야 합니다.

"initialLanguage="ko"

translations객체 (필수)

지원되는 모든 언어에 대한 번역 키와 값을 포함하는 객체입니다.

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

childrenReactNode (필수)

번역에 접근해야 하는 애플리케이션 컴포넌트들입니다.

languageManagerOptions객체 (선택사항)

언어 관리를 위한 추가 설정입니다.

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

사용 예제

기본 설정 (클라이언트 컴포넌트만)

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

서버 사이드 렌더링 (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>
  );
}

💡 왜 중요한가: 서버에서 쿠키로부터 언어를 읽음으로써, 초기 HTML이 클라이언트가 예상하는 것과 일치하도록 보장하여 하이드레이션 불일치를 방지합니다.

고급 설정

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

모범 사례

✅권장: 앱의 루트에 배치

모든 컴포넌트가 번역에 접근할 수 있도록 루트 레이아웃 레벨에서 항상 전체 애플리케이션을 I18nProvider로 감싸세요.

✅권장: 서버 사이드 언어 감지 사용

Next.js 애플리케이션의 경우, 하이드레이션 불일치를 방지하기 위해 항상 서버에서 쿠키로부터 언어를 읽으세요.

❌비권장: 여러 provider 중첩

I18nProvider 컴포넌트를 중첩하지 마세요. 루트 레벨에서 하나의 provider만 사용하세요.

❌비권장: initialLanguage를 동적으로 변경

initialLanguage prop은 한 번만 설정해야 합니다. 언어를 동적으로 변경하려면 useLanguageSwitcher의 changeLanguage()를 사용하세요.