createZustandI18n

설정

@hua-labs/i18n-core-zustand

Zustand 상태 관리와 i18n을 통합하는 어댑터입니다. 언어 설정을 Zustand 스토어에 영속화하고 자동으로 동기화합니다.

설치

Terminalbash

npm install @hua-labs/i18n-core-zustand

Importtsx

import { createZustandI18n } from '@hua-labs/i18n-core-zustand';

개요

createZustandI18n은 Zustand 상태 관리와 i18n을 통합하는 어댑터입니다. 기존 Zustand 스토어에 language와 setLanguage만 있으면 자동으로 연동됩니다.

동작 방식

1. Zustand 스토어의 language 상태를 감지

2. 스토어 변경 시 i18n 시스템에 자동 전파

3. i18n 변경 시 스토어에 역방향 동기화

4. 하이드레이션 완료 후 저장된 언어로 복원

Zustand 통합

기존 Zustand 스토어와 완벽하게 연동

언어 영속성

새로고침 후에도 언어 설정 유지

하이드레이션 안전

SSR/CSR 하이드레이션 에러 방지

양방향 동기화

i18n ↔ Zustand 자동 동기화

HTML lang 자동 업데이트

언어 변경 시 html[lang] 속성 자동 변경

디버그 로깅

동기화 과정 상세 로깅

API 레퍼런스

옵션


store (1st argument)*	UseBoundStore<StoreApi<ZustandLanguageStore>>	-	Zustand store with language and setLanguage. Passed as first positional argument, not in config object.
defaultLanguage	string	"ko"	Initial language for SSR (prevents hydration errors)
fallbackLanguage	string	-	Fallback language when translation key is missing
namespaces	string[]	["common"]	Translation namespaces to load
translationLoader	'api' \| 'static' \| 'custom'	-	How to load translations
translationApiPath	string	-	API path for 'api' loader mode
loadTranslations	(language: string, namespace: string) => Promise<Record<string, string>>	-	Custom loader function for 'custom' loader mode
initialTranslations	Record<string, Record<string, Record<string, string>>>	-	Pre-loaded translations for SSR (prevents flash)
supportedLanguages	Array<{ code, name, nativeName }> \| string[]	-	Supported language list
storageKey	string	"hua-i18n-storage"	Zustand persist storage key for hydration detection
autoUpdateHtmlLang	boolean	false	Auto-update document.documentElement.lang on language change
autoLanguageSync	boolean	-	Auto-sync language change events
debug	boolean	false	Enable debug logging

반환값


Provider	React.ComponentType<{ children: React.ReactNode }>	I18n Provider that syncs with Zustand store

코드 예시

docs:common.basicUsage

tsx

// store/useAppStore.ts
import { create } from 'zustand';
import { persist } from 'zustand/middleware';

interface AppStore {
  language: string;
  setLanguage: (lang: string) => void;
}

export const useAppStore = create<AppStore>()(
  persist(
    (set) => ({
      language: 'ko',
      setLanguage: (lang) => set({ language: lang }),
    }),
    { name: 'app-storage' }
  )
);

i18n:examples.providerSetup

tsx

// app/layout.tsx
import { createZustandI18n } from '@hua-labs/i18n-core-zustand';
import { useAppStore } from '@/store/useAppStore';

const I18nProvider = createZustandI18n(useAppStore, {
  defaultLanguage: 'ko',
  namespaces: ['common', 'navigation'],
  storageKey: 'app-storage',
  autoUpdateHtmlLang: true,
  debug: process.env.NODE_ENV === 'development',
});

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <I18nProvider>{children}</I18nProvider>
      </body>
    </html>
  );
}

i18n:examples.useWithStore

tsx

// Language persists across sessions via Zustand store
import { useTranslation } from '@hua-labs/hua';
import { useAppStore } from '@/store/useAppStore';

function LanguageSwitcher() {
  const { t } = useTranslation();
  // Language changes through store automatically sync with i18n
  const { language, setLanguage } = useAppStore();

  return (
    <select value={language} onChange={(e) => setLanguage(e.target.value)}>
      <option value="ko">한국어</option>
      <option value="en">English</option>
    </select>
  );
}

사용 사례

언어 영속화

새로고침 후에도 언어 설정 유지

Zustand 통합

기존 Zustand 스토어와 연동

하이드레이션 안전

SSR/CSR 하이드레이션 에러 방지

createCoreI18n