Skip to content
HUA Docs
패키지 목록

@hua-labs/i18n-core-zustand

v1.1.0-alpha.1
Zustand
Adapter

Zustand 상태관리와 i18n-core를 타입 안전하게 통합하는 어댑터. 양방향 동기화, 영속성, 하이드레이션 안전.

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

주요 기능

양방향 동기화

Zustand 스토어와 i18n-core 상태 자동 동기화

영속성 지원

Zustand persist 미들웨어와 완벽 호환

하이드레이션 안전

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-core를 통합하는 Provider 컴포넌트를 생성합니다.

옵션Type설명
defaultLanguagestringSSR 초기 언어
fallbackLanguagestring폴백 언어
namespacesstring[]번역 네임스페이스
autoUpdateHtmlLangbooleanhtml[lang] 자동 업데이트
debugboolean디버그 로그 활성화

useZustandI18n(store)

Zustand 스토어의 언어 상태를 직접 사용하는 훅입니다.

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

관련 패키지

@hua-labs/i18n-core
@hua-labs/state
zustand