React i18next

const greeting = language === 'ko' ? '안녕하세요' : 'Hello';

┌─────────────────────────────────┐
│       react-i18next             │  ← React 바인딩 (훅, HOC, 컴포넌트)
├─────────────────────────────────┤
│       i18next (코어)            │  ← 번역 엔진, 보간, 복수형, 포매팅
├─────────────────────────────────┤
│       플러그인들                 │  ← 백엔드, 언어감지, 캐시, 후처리
└─────────────────────────────────┘

// src/i18n.ts
import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import LanguageDetector from 'i18next-browser-languagedetector';
import Backend from 'i18next-http-backend';

i18n
  .use(Backend)                // 번역 파일 로딩
  .use(LanguageDetector)       // 사용자 언어 감지
  .use(initReactI18next)       // React 바인딩 연결
  .init({
    fallbackLng: 'en',
    debug: process.env.NODE_ENV === 'development',

    ns: ['common', 'auth', 'dashboard'],
    defaultNS: 'common',

    interpolation: {
      escapeValue: false,      // React가 이미 XSS 방지를 하므로 불필요
    },

    backend: {
      loadPath: '/locales/{{lng}}/{{ns}}.json',
    },

    detection: {
      order: ['querystring', 'localStorage', 'navigator'],
      caches: ['localStorage'],
    },
  });

export default i18n;

// src/main.tsx
import './i18n';  // 사이드이펙트 import — 이것만으로 초기화 완료
import { App } from './App';

detection: {
  // 감지 순서: 왼쪽부터 시도
  order: ['querystring', 'cookie', 'localStorage', 'sessionStorage', 'navigator', 'htmlTag', 'path', 'subdomain'],

  // 감지된 언어를 저장할 위치
  caches: ['localStorage', 'cookie'],

  // 쿼리스트링 파라미터 이름
  lookupQuerystring: 'lng',

  // localStorage 키 이름
  lookupLocalStorage: 'i18nextLng',

  // 쿠키 이름
  lookupCookie: 'i18next',

  // path에서 언어 위치 (0-indexed)
  lookupFromPathIndex: 0,

  // 캐시 만료 (쿠키)
  cookieMinutes: 10080, // 7일
}

const customDetector = {
  name: 'userProfileDetector',

  lookup(options) {
    // 예: API에서 가져온 사용자 프로필의 언어 설정
    const userLang = window.__USER_PROFILE__?.language;
    return userLang || undefined; // undefined면 다음 디텍터로 넘어감
  },

  cacheUserLanguage(lng, options) {
    // 사용자가 언어를 변경했을 때 저장 로직
    // API 호출로 서버에도 반영할 수 있다
  },
};

const languageDetector = new LanguageDetector();
languageDetector.addDetector(customDetector);

i18n
  .use(languageDetector)
  .init({
    detection: {
      order: ['userProfileDetector', 'localStorage', 'navigator'],
    },
  });

/locales
  /ko
    common.json      ← 공통 (버튼, 네비게이션, 에러 메시지)
    auth.json         ← 인증 (로그인, 회원가입)
    dashboard.json    ← 대시보드 전용
    settings.json     ← 설정 페이지
  /en
    common.json
    auth.json
    dashboard.json
    settings.json

// /locales/ko/common.json
{
  "button": {
    "save": "저장",
    "cancel": "취소",
    "delete": "삭제"
  },
  "error": {
    "network": "네트워크 오류가 발생했습니다",
    "unauthorized": "로그인이 필요합니다"
  }
}

// /locales/ko/auth.json
{
  "login": {
    "title": "로그인",
    "emailPlaceholder": "이메일을 입력하세요",
    "passwordPlaceholder": "비밀번호를 입력하세요",
    "submit": "로그인",
    "forgotPassword": "비밀번호를 잊으셨나요?"
  },
  "register": {
    "title": "회원가입",
    "agree": "이용약관에 동의합니다"
  }
}

// 단일 네임스페이스
const { t } = useTranslation('auth');
t('login.title');  // "로그인"

// 복수 네임스페이스
const { t } = useTranslation(['dashboard', 'common']);
t('widget.title');            // dashboard의 키 (첫 번째가 기본)
t('button.save', { ns: 'common' });  // 명시적으로 common 지정

// 콜론 표기법 (어디서든 다른 네임스페이스 참조)
t('common:button.save');

// i18n 초기화에서 초기 로딩할 네임스페이스만 지정
i18n.init({
  ns: ['common'],         // 앱 시작 시 common만 로딩
  defaultNS: 'common',
  backend: {
    loadPath: '/locales/{{lng}}/{{ns}}.json',
  },
});

// DashboardPage.tsx — 이 컴포넌트가 렌더링될 때 dashboard.json 로딩
function DashboardPage() {
  const { t, ready } = useTranslation('dashboard');

  if (!ready) return <Skeleton />;  // Suspense 미사용 시 로딩 처리

  return <h1>{t('title')}</h1>;
}

// Suspense 모드 (react.useSuspense: true가 기본값)
function DashboardPage() {
  const { t } = useTranslation('dashboard');
  return <h1>{t('title')}</h1>;  // 로딩 중이면 Suspense fallback 표시
}

// 상위에서 Suspense로 감싸기
<Suspense fallback={<Skeleton />}>
  <DashboardPage />
</Suspense>

{
  "greeting": "{{name}}님, 환영합니다!",
  "itemCount": "{{count}}개의 항목이 있습니다",
  "lastLogin": "마지막 접속: {{date, datetime}}"
}

t('greeting', { name: '준혁' });
// "준혁님, 환영합니다!"

t('itemCount', { count: 42 });
// "42개의 항목이 있습니다"

{
  "price": "가격: {{amount, number(style: currency; currency: KRW)}}",
  "date": "{{val, datetime(dateStyle: long)}}",
  "percent": "진행률: {{val, number(style: percent)}}"
}

t('price', { amount: 15000 });
// "가격: ₩15,000"

t('date', { val: new Date() });
// "2026년 2월 15일"

t('percent', { val: 0.85 });
// "진행률: 85%"

i18n.init({
  interpolation: {
    escapeValue: false,
  },
});

// 커스텀 포맷 등록
i18n.services.formatter.add('relativeTime', (value, lng, options) => {
  const rtf = new Intl.RelativeTimeFormat(lng, { numeric: 'auto' });
  const diff = Math.round((value - Date.now()) / 86400000);
  return rtf.format(diff, 'day');
});

{
  "lastSeen": "{{date, relativeTime}}"
}

{
  "appName": "포토부스",
  "welcome": "$t(appName)에 오신 것을 환영합니다!"
}

t('welcome');
// "포토부스에 오신 것을 환영합니다!"

{
  "item_one": "{{count}} item",
  "item_other": "{{count}} items"
}

t('item', { count: 1 });   // "1 item"
t('item', { count: 5 });   // "5 items"
t('item', { count: 0 });   // "0 items"

// 러시아어 예시 (ru.json)
{
  "item_one": "{{count}} элемент",
  "item_few": "{{count}} элемента",
  "item_many": "{{count}} элементов",
  "item_other": "{{count}} элементов"
}

{
  "item_other": "{{count}}개의 항목"
}

{
  "item_other": "{{count}}개의 항목이 있습니다",
  "itemEmpty": "항목이 없습니다"
}

count === 0 ? t('itemEmpty') : t('item', { count })

{
  "friend_male": "남사친",
  "friend_female": "여사친",
  "greeting_formal": "안녕하십니까, {{name}}님",
  "greeting_casual": "안녕, {{name}}!"
}

t('friend', { context: 'male' });     // "남사친"
t('friend', { context: 'female' });   // "여사친"

t('greeting', { context: 'formal', name: '김철수' });
// "안녕하십니까, 김철수님"

{
  "terms": "<0>이용약관</0>과 <1>개인정보처리방침</1>에 동의합니다",
  "bold": "총 <strong>{{count}}개</strong>의 결과"
}

import { Trans } from 'react-i18next';

<Trans i18nKey="terms">
  <Link to="/terms">이용약관</Link>과
  <Link to="/privacy">개인정보처리방침</Link>에 동의합니다
</Trans>

<Trans
  i18nKey="bold"
  values={{ count: 42 }}
  components={{ strong: <strong /> }}
/>
// "총 <strong>42개</strong>의 결과" 렌더링

function MyComponent() {
  const { t, i18n, ready } = useTranslation('auth');

  return (
    <div>
      <h1>{t('login.title')}</h1>
      <p>현재 언어: {i18n.language}</p>
      <button onClick={() => i18n.changeLanguage('en')}>
        English
      </button>
    </div>
  );
}

const { i18n } = useTranslation();

// 언어 변경 — Promise 반환
await i18n.changeLanguage('en');

// 현재 언어 확인
console.log(i18n.language);          // 실제 사용 중인 언어 (resolved)
console.log(i18n.resolvedLanguage);  // fallback 체인 고려한 최종 언어

// 기본값 (키가 없을 때)
t('missing.key', 'Default text');
t('missing.key', { defaultValue: 'Default text' });

// 네임스페이스 지정
t('key', { ns: 'auth' });

// 보간
t('greeting', { name: '준혁' });

// 복수형
t('item', { count: 5 });

// 컨텍스트
t('friend', { context: 'male' });

// 리턴 타입 지정
t('key', { returnObjects: true });  // 객체/배열 반환 가능

// 키 존재 확인
i18n.exists('some.key');  // boolean

import ko from './locales/ko/common.json';
import en from './locales/en/common.json';

i18n.init({
  resources: {
    ko: { common: ko },
    en: { common: en },
  },
});

import Backend from 'i18next-http-backend';

i18n.use(Backend).init({
  backend: {
    loadPath: '/locales/{{lng}}/{{ns}}.json',
    // 또는 CDN
    // loadPath: 'https://cdn.example.com/i18n/{{lng}}/{{ns}}.json',
    requestOptions: {
      cache: 'no-store',  // 개발 중 캐시 방지
    },
  },
});

import ko from './locales/ko/common.json';

i18n.use(Backend).init({
  partialBundledLanguages: true,
  resources: {
    ko: { common: ko },  // 한국어는 번들에 포함
  },
  backend: {
    loadPath: '/locales/{{lng}}/{{ns}}.json',  // 나머지는 동적 로딩
  },
});

// src/@types/i18next.d.ts
import 'i18next';
import common from '../locales/ko/common.json';
import auth from '../locales/ko/auth.json';

declare module 'i18next' {
  interface CustomTypeOptions {
    defaultNS: 'common';
    resources: {
      common: typeof common;
      auth: typeof auth;
    };
  }
}

interface CustomTypeOptions {
  returnNull: false;         // t()가 null 반환하지 않음 → 반환 타입에서 null 제거
  returnEmptyString: false;  // 빈 문자열도 반환하지 않음
}

// 서버 유틸
import { createInstance } from 'i18next';
import { initReactI18next } from 'react-i18next/initReactI18next';

export async function getServerTranslation(lng: string, ns: string) {
  const i18nInstance = createInstance();
  await i18nInstance
    .use(initReactI18next)
    .init({
      lng,
      ns,
      resources: await loadResources(lng, ns),
    });
  return {
    t: i18nInstance.getFixedT(lng, ns),
    i18n: i18nInstance,
  };
}

// ❌ 나쁜 예 — 의미 불명확, 계층 없음
{
  "text1": "저장",
  "msg": "성공했습니다"
}

// ✅ 좋은 예 — 기능.컴포넌트.요소 계층
{
  "auth": {
    "login": {
      "title": "로그인",
      "submit": "로그인",
      "error": {
        "invalidEmail": "올바른 이메일을 입력하세요",
        "wrongPassword": "비밀번호가 일치하지 않습니다"
      }
    }
  }
}

i18n.init({
  saveMissing: true,           // 누락된 키를 백엔드에 저장
  missingKeyHandler: (lngs, ns, key, fallbackValue) => {
    if (process.env.NODE_ENV === 'development') {
      console.warn(`[i18n] Missing: ${ns}:${key}`);
    }
    // 프로덕션에서는 로깅 서비스에 보고
  },
});

function LanguageSwitcher() {
  const { i18n } = useTranslation();

  const languages = [
    { code: 'ko', label: '한국어', flag: '🇰🇷' },
    { code: 'en', label: 'English', flag: '🇺🇸' },
    { code: 'ja', label: '日本語', flag: '🇯🇵' },
  ];

  return (
    <select
      value={i18n.language}
      onChange={(e) => i18n.changeLanguage(e.target.value)}
    >
      {languages.map(({ code, label, flag }) => (
        <option key={code} value={code}>
          {flag} {label}
        </option>
      ))}
    </select>
  );
}

const formatter = new Intl.DateTimeFormat(i18n.language, {
  dateStyle: 'long',
  timeStyle: 'short',
});

return <span>{formatter.format(new Date())}</span>;
// "2026년 2월 15일 오후 9:11" (ko)
// "February 15, 2026, 9:11 PM" (en)