Skip to content
Docs
패키지 목록

@hua-labs/i18n-core-zustand

v2.1.0
Zustand
Adapter

Zustand adapter for i18n-core with hydration-safe language syncing.

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

주요 기능

양방향 동기화

Zustand 스토어와 i18n 상태가 양방향으로 동기화됩니다.

영속성 지원

언어 설정이 로컬 스토리지에 저장됩니다.

하이드레이션 안전

SSR 하이드레이션 불일치를 방지합니다.

빠른 시작

1. Zustand 스토어 준비

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

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

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

2. Provider 생성

typescript
// providers/I18nProvider.tsx
import { createZustandI18n } from '@hua-labs/i18n-core-zustand';
import { useAppStore } from '../store/useAppStore';

export const I18nProvider = createZustandI18n(useAppStore, {
  defaultLanguage: 'ko',
  fallbackLanguage: 'en',
  namespaces: ['common', 'navigation'],
  translationLoader: 'static',
  debug: process.env.NODE_ENV === 'development',
  autoUpdateHtmlLang: true,
});

3. 레이아웃에 적용

tsx
// app/layout.tsx
import { I18nProvider } from '../providers/I18nProvider';

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

4. 컴포넌트에서 사용

tsx
'use client';

import { useTranslation, useLanguageChange } from '@hua-labs/i18n-core';
import { useAppStore } from '../store/useAppStore';

function LanguageSelector() {
  const { t } = useTranslation();
  const { changeLanguage, supportedLanguages } = useLanguageChange();

  // Zustand 스토어도 자동 동기화됨
  const storeLanguage = useAppStore((s) => s.language);

  return (
    <div>
      <p>{t('common:welcome')}</p>
      <select onChange={(e) => changeLanguage(e.target.value)}>
        {supportedLanguages.map((lang) => (
          <option key={lang.code} value={lang.code}>
            {lang.nativeName}
          </option>
        ))}
      </select>
    </div>
  );
}

API Reference

createZustandI18n(store, config)

Zustand 스토어를 기반으로 i18n Provider 컴포넌트를 생성합니다. 언어 상태가 스토어와 자동 동기화됩니다.

옵션Type설명
defaultLanguagestring초기 언어 설정
fallbackLanguagestring폴백 언어 설정
namespacesstring[]사용할 네임스페이스 목록
autoUpdateHtmlLangbooleanHTML lang 속성 자동 감지
debugboolean디버그 모드 활성화

useZustandI18n(store)

Zustand 스토어에서 언어 상태를 읽고 설정하는 훅입니다. i18n Provider 내에서 사용하세요.

typescript
const { language, setLanguage } = useZustandI18n(useAppStore);

관련 패키지