npm - @hua-labs/i18n-core-zustand - Versions diffs - 1.0.0 - Mend

@hua-labs/i18n-core-zustand 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2024 HUA Labs Team
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,249 @@
+# @hua-labs/i18n-core-zustand
+Type-safe adapter package for integrating Zustand state management with `@hua-labs/i18n-core`.
+## Installation
+```bash
+pnpm add @hua-labs/i18n-core-zustand zustand
+# or
+npm install @hua-labs/i18n-core-zustand zustand
+# or
+yarn add @hua-labs/i18n-core-zustand zustand
+```
+## Requirements
+- Your Zustand store must have `language: string` and `setLanguage: (lang: string) => void`.
+## Usage
+### 1. Basic Usage (Create Provider)
+```tsx
+// lib/i18n-config.ts
+import { createZustandI18n } from '@hua-labs/i18n-core-zustand';
+import { useAppStore } from '../store/useAppStore';
+export const I18nProvider = createZustandI18n(useAppStore, {
+  fallbackLanguage: 'en',
+  namespaces: ['common', 'navigation', 'footer'],
+  translationLoader: 'api',
+  translationApiPath: '/api/translations',
+  defaultLanguage: 'ko', // SSR initial language (prevents hydration errors)
+  debug: process.env.NODE_ENV === 'development'
+});
+```
+```tsx
+// app/layout.tsx
+import { I18nProvider } from './lib/i18n-config';
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <I18nProvider>{children}</I18nProvider>
+      </body>
+    </html>
+  );
+}
+```
+### 2. Zustand Store Example
+```tsx
+// store/useAppStore.ts
+import { create } from 'zustand';
+import { persist } from 'zustand/middleware';
+interface AppState {
+  language: 'ko' | 'en';
+  setLanguage: (lang: 'ko' | 'en') => void;
+}
+export const useAppStore = create<AppState>()(
+  persist(
+    (set) => ({
+      language: 'ko',
+      setLanguage: (lang) => set({ language: lang }),
+    }),
+    {
+      name: 'app-storage',
+      partialize: (state) => ({ language: state.language }),
+    }
+  )
+);
+```
+### 3. Using Translations
+```tsx
+// components/MyComponent.tsx
+import { useTranslation } from '@hua-labs/i18n-core';
+import { useAppStore } from '../store/useAppStore';
+export default function MyComponent() {
+  const { t } = useTranslation();
+  const { language, setLanguage } = useAppStore();
+  return (
+    <div>
+      <h1>{t('common:welcome')}</h1>
+      <button onClick={() => setLanguage(language === 'ko' ? 'en' : 'ko')}>
+        {language === 'ko' ? 'English' : '한국어'}
+      </button>
+    </div>
+  );
+}
+```
+### 4. Using with SSR
+```tsx
+// app/layout.tsx (Server Component)
+import { loadSSRTranslations } from './lib/ssr-translations';
+import { createZustandI18n } from '@hua-labs/i18n-core-zustand';
+import { useAppStore } from './store/useAppStore';
+export default async function RootLayout({ children }) {
+  // Load translations from SSR
+  const ssrTranslations = await loadSSRTranslations('ko');
+  const I18nProvider = createZustandI18n(useAppStore, {
+    fallbackLanguage: 'en',
+    namespaces: ['common', 'navigation', 'footer'],
+    translationLoader: 'api',
+    translationApiPath: '/api/translations',
+    defaultLanguage: 'ko', // Same initial language as SSR
+    initialTranslations: ssrTranslations, // Pass SSR translations
+    debug: process.env.NODE_ENV === 'development'
+  });
+  return (
+    <html lang="ko">
+      <body>
+        <I18nProvider>{children}</I18nProvider>
+      </body>
+    </html>
+  );
+}
+```
+## API
+### `createZustandI18n(store, config)`
+Creates a Provider that integrates Zustand store with i18n-core.
+**Parameters:**
+- `store`: Zustand store (must have `language` and `setLanguage` methods)
+- `config`: i18n configuration (same as `I18nConfig` except `defaultLanguage`)
+**Returns:**
+- React Provider component
+**Configuration Options:**
+```ts
+interface ZustandI18nConfig {
+  // Initial language to match SSR (prevents hydration errors)
+  defaultLanguage?: string;
+  // Fallback language
+  fallbackLanguage?: string;
+  // Namespace list
+  namespaces?: string[];
+  // Debug mode
+  debug?: boolean;
+  // Custom translation loader
+  loadTranslations?: (language: string, namespace: string) => Promise<Record<string, string>>;
+  // Translation loader type
+  translationLoader?: 'api' | 'static' | 'custom';
+  // API path (when translationLoader is 'api')
+  translationApiPath?: string;
+  // SSR initial translation data
+  initialTranslations?: Record<string, Record<string, Record<string, string>>>;
+  // Auto language sync (always false in this package)
+  autoLanguageSync?: boolean;
+}
+```
+### `useZustandI18n(store)`
+Provides i18n hook integrated with Zustand store.
+**Parameters:**
+- `store`: Zustand store
+**Returns:**
+- `{ language, setLanguage }`: Language state and change function
+**Note:** Use `useTranslation` hook for actual translations:
+```tsx
+import { useTranslation } from '@hua-labs/i18n-core';
+import { useZustandI18n } from '@hua-labs/i18n-core-zustand';
+import { useAppStore } from './store/useAppStore';
+function MyComponent() {
+  const { t } = useTranslation(); // Translation function
+  const { language, setLanguage } = useZustandI18n(useAppStore); // Language state
+  return (
+    <div>
+      <p>{t('common:welcome')}</p>
+      <button onClick={() => setLanguage('en')}>English</button>
+    </div>
+  );
+}
+```
+## Features
+- **Type-safe**: Full TypeScript support
+- **Minimal dependencies**: Only Zustand as peer dependency
+- **Auto synchronization**: Automatically syncs Zustand store changes to i18n
+- **Unidirectional data flow**: Zustand store is the source of truth
+- **SSR compatible**: Language syncs after hydration completes (prevents hydration errors)
+- **Circular reference prevention**: Safe language synchronization mechanism
+## How It Works
+1. **Initialization**: `createZustandI18n` wraps `createCoreI18n` to create the base Provider.
+2. **Language synchronization**: Detects Zustand store language changes and automatically syncs to i18n.
+3. **Hydration**: Only syncs language after hydration completes to prevent SSR/client hydration errors.
+4. **Circular reference prevention**: Uses `useRef` to prevent infinite loops and maintains unidirectional data flow.
+## Caveats
+1. **Zustand store structure**: Store must have `language` and `setLanguage`.
+2. **autoLanguageSync**: This package automatically disables `autoLanguageSync` (Zustand adapter handles it directly).
+3. **Language changes**: Language changes must be made through Zustand store's `setLanguage`.
+4. **SSR initial language**: Use `defaultLanguage` option to set the same initial language as SSR (prevents hydration errors).
+5. **Hydration**: Zustand store language only syncs to i18n after hydration completes.
+## Examples
+- **[CodeSandbox Template](../../examples/codesandbox-template/)** - Quick start with Zustand
+- **[Next.js Example](../../examples/next-app-router-example/)** - Complete Next.js example
+## Documentation
+- [Hydration Guide](./docs/HYDRATION.md) - Hydration process and troubleshooting
+## Related Packages
+- `@hua-labs/i18n-core`: Core i18n library
+- `@hua-labs/i18n-loaders`: Production-ready loaders and caching utilities
+## License
+MIT

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,104 @@
+/**
+ * @hua-labs/i18n-core-zustand - Zustand 어댑터
+ *
+ * Zustand 상태관리와 i18n-core를 타입 안전하게 통합하는 어댑터입니다.
+ *
+ * @example
+ * ```tsx
+ * import { createZustandI18n } from '@hua-labs/i18n-core-zustand';
+ * import { useAppStore } from './store/useAppStore';
+ *
+ * // Zustand 스토어에 language와 setLanguage가 있어야 함
+ * const I18nProvider = createZustandI18n(useAppStore, {
+ *   fallbackLanguage: 'en',
+ *   namespaces: ['common', 'navigation']
+ * });
+ *
+ * export default function Layout({ children }) {
+ *   return <I18nProvider>{children}</I18nProvider>;
+ * }
+ * ```
+ */
+import React from 'react';
+import type { StoreApi, UseBoundStore } from 'zustand';
+/**
+ * Zustand 스토어에서 언어 관련 상태를 가져오는 인터페이스
+ */
+export interface ZustandLanguageStore {
+    language: string | 'ko' | 'en';
+    setLanguage: (lang: string | 'ko' | 'en') => void;
+}
+/**
+ * Zustand 스토어 어댑터 인터페이스
+ */
+export interface ZustandI18nAdapter {
+    getLanguage: () => string;
+    setLanguage: (lang: string) => void;
+    subscribe: (callback: (lang: string) => void) => () => void;
+}
+/**
+ * Zustand 스토어와 i18n-core를 통합하는 Provider 생성
+ *
+ * @param store - Zustand 스토어 (language와 setLanguage 메서드 필요)
+ * @param config - i18n 설정 (defaultLanguage는 스토어에서 가져옴)
+ * @returns I18nProvider 컴포넌트
+ *
+ * @example
+ * ```tsx
+ * import { createZustandI18n } from '@hua-labs/i18n-core-zustand';
+ * import { useAppStore } from './store/useAppStore';
+ *
+ * const I18nProvider = createZustandI18n(useAppStore, {
+ *   fallbackLanguage: 'en',
+ *   namespaces: ['common', 'navigation', 'footer'],
+ *   translationLoader: 'api',
+ *   debug: process.env.NODE_ENV === 'development'
+ * });
+ *
+ * export default function RootLayout({ children }) {
+ *   return <I18nProvider>{children}</I18nProvider>;
+ * }
+ * ```
+ */
+export interface ZustandI18nConfig {
+    defaultLanguage?: string;
+    fallbackLanguage?: string;
+    namespaces?: string[];
+    debug?: boolean;
+    loadTranslations?: (language: string, namespace: string) => Promise<Record<string, string>>;
+    translationLoader?: 'api' | 'static' | 'custom';
+    translationApiPath?: string;
+    initialTranslations?: Record<string, Record<string, Record<string, string>>>;
+    autoLanguageSync?: boolean;
+}
+export declare function createZustandI18n(store: UseBoundStore<StoreApi<ZustandLanguageStore>>, config?: ZustandI18nConfig): React.ComponentType<{
+    children: React.ReactNode;
+}>;
+/**
+ * Zustand 스토어와 i18n-core를 통합하는 Hook
+ *
+ * @param store - Zustand 스토어
+ * @returns { language, setLanguage, t } - i18n 훅과 동일한 인터페이스
+ *
+ * @example
+ * ```tsx
+ * import { useZustandI18n } from '@hua-labs/i18n-core-zustand';
+ * import { useAppStore } from './store/useAppStore';
+ *
+ * function MyComponent() {
+ *   const { language, setLanguage, t } = useZustandI18n(useAppStore);
+ *
+ *   return (
+ *     <div>
+ *       <p>{t('common:welcome')}</p>
+ *       <button onClick={() => setLanguage('en')}>English</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useZustandI18n(store: UseBoundStore<StoreApi<ZustandLanguageStore>>): {
+    language: string;
+    setLanguage: (lang: string) => void;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAEvD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;IAC/B,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,KAAK,IAAI,CAAC;CACnD;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,MAAM,CAAC;IAC1B,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,SAAS,EAAE,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;CAC7D;AA+BD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,iBAAiB;IAChC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC5F,iBAAiB,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAChD,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAC7E,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,aAAa,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAAC,EACpD,MAAM,CAAC,EAAE,iBAAiB,GACzB,KAAK,CAAC,aAAa,CAAC;IAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAAE,CAAC,CAyLpD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,aAAa,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAAC;;wBAS3C,MAAM;EAYhB"}

package/dist/index.js ADDED Viewed

@@ -0,0 +1,245 @@
+/**
+ * @hua-labs/i18n-core-zustand - Zustand 어댑터
+ *
+ * Zustand 상태관리와 i18n-core를 타입 안전하게 통합하는 어댑터입니다.
+ *
+ * @example
+ * ```tsx
+ * import { createZustandI18n } from '@hua-labs/i18n-core-zustand';
+ * import { useAppStore } from './store/useAppStore';
+ *
+ * // Zustand 스토어에 language와 setLanguage가 있어야 함
+ * const I18nProvider = createZustandI18n(useAppStore, {
+ *   fallbackLanguage: 'en',
+ *   namespaces: ['common', 'navigation']
+ * });
+ *
+ * export default function Layout({ children }) {
+ *   return <I18nProvider>{children}</I18nProvider>;
+ * }
+ * ```
+ */
+import React from 'react';
+import { createCoreI18n, useTranslation } from '@hua-labs/i18n-core';
+/**
+ * Zustand 스토어에서 어댑터 생성
+ */
+function createZustandAdapter(store) {
+    return {
+        getLanguage: () => store.getState().language,
+        setLanguage: (lang) => {
+            const currentLang = store.getState().language;
+            if (currentLang !== lang) {
+                store.getState().setLanguage(lang);
+            }
+        },
+        subscribe: (callback) => {
+            // Zustand의 subscribe를 사용하여 언어 변경 감지
+            let prevLanguage = store.getState().language;
+            return store.subscribe((state) => {
+                const currentLanguage = state.language;
+                if (currentLanguage !== prevLanguage) {
+                    prevLanguage = currentLanguage;
+                    callback(currentLanguage);
+                }
+            });
+        }
+    };
+}
+export function createZustandI18n(store, config) {
+    const adapter = createZustandAdapter(store);
+    // 하이드레이션 에러 방지: SSR과 동일한 초기 언어 사용
+    // config에 defaultLanguage가 있으면 사용, 없으면 'ko' (SSR 기본값과 일치)
+    // 하이드레이션 완료 후 저장된 언어로 자동 동기화됨
+    const initialLanguage = config?.defaultLanguage || 'ko';
+    const storeLanguage = adapter.getLanguage();
+    // createCoreI18n으로 기본 Provider 생성
+    const BaseI18nProvider = createCoreI18n({
+        ...config,
+        defaultLanguage: initialLanguage, // SSR과 동일한 초기 언어 사용
+        // Zustand 어댑터가 직접 언어 동기화 처리하므로 autoLanguageSync 비활성화
+        autoLanguageSync: false
+    });
+    // 언어 동기화 래퍼 컴포넌트 (Provider 내부에서만 사용)
+    // BaseI18nProvider가 I18nProvider를 렌더링하므로, 그 자식으로 들어가면 useTranslation 사용 가능
+    function LanguageSyncWrapper({ children: innerChildren }) {
+        const debug = config?.debug ?? false;
+        // useTranslation은 I18nProvider 내부에서만 사용 가능
+        // BaseI18nProvider가 I18nProvider를 렌더링하므로 여기서 사용 가능
+        const { setLanguage: setI18nLanguage, currentLanguage, isInitialized } = useTranslation();
+        const hydrationStateRef = React.useRef({
+            isComplete: false,
+            isInitialized: false,
+            previousStoreLanguage: null,
+            currentI18nLanguage: currentLanguage,
+        });
+        // currentLanguage가 변경되면 상태 업데이트
+        React.useEffect(() => {
+            hydrationStateRef.current.currentI18nLanguage = currentLanguage;
+        }, [currentLanguage]);
+        // 하이드레이션 완료 감지 및 언어 동기화
+        React.useEffect(() => {
+            if (typeof window === 'undefined' || hydrationStateRef.current.isComplete) {
+                return;
+            }
+            const checkHydration = () => {
+                if (hydrationStateRef.current.isComplete) {
+                    return;
+                }
+                hydrationStateRef.current.isComplete = true;
+                hydrationStateRef.current.isInitialized = isInitialized;
+                if (debug) {
+                    console.log(`✅ [ZUSTAND-I18N] Hydration complete`);
+                }
+                // 하이드레이션 완료 후 저장된 언어로 동기화
+                if (isInitialized) {
+                    const storeLanguage = store.getState().language;
+                    const state = hydrationStateRef.current;
+                    // initialLanguage와 다르고, 현재 i18n 언어와도 다를 때만 동기화
+                    if (storeLanguage !== initialLanguage && storeLanguage !== state.currentI18nLanguage) {
+                        if (debug) {
+                            console.log(`🔄 [ZUSTAND-I18N] Hydration complete, syncing language: ${state.currentI18nLanguage} -> ${storeLanguage}`);
+                        }
+                        setI18nLanguage(storeLanguage);
+                        state.previousStoreLanguage = storeLanguage;
+                    }
+                    else {
+                        if (debug) {
+                            console.log(`⏭️ [ZUSTAND-I18N] Hydration complete, no sync needed (store: ${storeLanguage}, initial: ${initialLanguage}, current: ${state.currentI18nLanguage})`);
+                        }
+                        state.previousStoreLanguage = storeLanguage;
+                    }
+                }
+            };
+            // 브라우저가 준비되면 하이드레이션 완료로 간주
+            const timeoutId = setTimeout(() => {
+                requestAnimationFrame(checkHydration);
+            }, 0);
+            return () => clearTimeout(timeoutId);
+        }, [isInitialized, setI18nLanguage, initialLanguage, debug]);
+        // 언어 동기화 함수 (재사용)
+        const syncLanguageFromStore = React.useCallback(() => {
+            const state = hydrationStateRef.current;
+            if (!state.isInitialized || !state.isComplete) {
+                return;
+            }
+            const storeLanguage = store.getState().language;
+            if (storeLanguage !== state.currentI18nLanguage && storeLanguage !== initialLanguage) {
+                if (debug) {
+                    console.log(`🔄 [ZUSTAND-I18N] Syncing language from store: ${state.currentI18nLanguage} -> ${storeLanguage}`);
+                }
+                setI18nLanguage(storeLanguage);
+                state.previousStoreLanguage = storeLanguage;
+            }
+        }, [setI18nLanguage, initialLanguage, debug]);
+        // 언어 변경 구독 설정
+        React.useEffect(() => {
+            // Translator가 초기화된 후에만 동기화
+            if (!isInitialized) {
+                return;
+            }
+            const state = hydrationStateRef.current;
+            state.isInitialized = true;
+            // 초기 스토어 언어 설정
+            if (state.previousStoreLanguage === null) {
+                state.previousStoreLanguage = store.getState().language;
+            }
+            // Zustand 스토어 변경 감지
+            const unsubscribe = adapter.subscribe((newLanguage) => {
+                // 이전 언어와 다를 때만 처리
+                if (newLanguage !== state.previousStoreLanguage) {
+                    state.previousStoreLanguage = newLanguage;
+                    // 하이드레이션 완료 후에만 동기화
+                    if (state.isComplete) {
+                        // 현재 i18n 언어와 다를 때만 동기화 (무한 루프 방지)
+                        if (newLanguage !== state.currentI18nLanguage) {
+                            if (debug) {
+                                console.log(`🔄 [ZUSTAND-I18N] Store language changed, syncing to i18n: ${state.currentI18nLanguage} -> ${newLanguage}`);
+                            }
+                            setI18nLanguage(newLanguage);
+                        }
+                        else {
+                            if (debug) {
+                                console.log(`⏭️ [ZUSTAND-I18N] Store language changed but i18n already synced: ${newLanguage}`);
+                            }
+                        }
+                    }
+                    else {
+                        // 하이드레이션 완료 전에는 로그만 출력
+                        if (debug) {
+                            console.log(`⏳ [ZUSTAND-I18N] Store language changed but hydration not complete yet: ${newLanguage}`);
+                        }
+                    }
+                }
+            });
+            // 하이드레이션이 이미 완료되었다면 즉시 동기화
+            if (state.isComplete) {
+                const storeLanguage = store.getState().language;
+                // initialLanguage와 다르고, 현재 i18n 언어와도 다를 때만 동기화
+                if (storeLanguage !== initialLanguage && storeLanguage !== state.currentI18nLanguage) {
+                    if (debug) {
+                        console.log(`🔄 [ZUSTAND-I18N] Already hydrated, syncing language: ${state.currentI18nLanguage} -> ${storeLanguage}`);
+                    }
+                    setI18nLanguage(storeLanguage);
+                    state.previousStoreLanguage = storeLanguage;
+                }
+                else {
+                    if (debug) {
+                        console.log(`⏭️ [ZUSTAND-I18N] Already hydrated, no sync needed (store: ${storeLanguage}, initial: ${initialLanguage}, current: ${state.currentI18nLanguage})`);
+                    }
+                }
+            }
+            return unsubscribe;
+        }, [isInitialized, setI18nLanguage, initialLanguage, debug]);
+        // 하이드레이션 완료 후 언어 동기화를 위한 별도 useEffect
+        // hydratedRef는 ref이므로 의존성으로 사용할 수 없음
+        // 대신 하이드레이션 완료 시점에 직접 syncLanguageFromStore 호출
+        return React.createElement(React.Fragment, null, innerChildren);
+    }
+    // Zustand 스토어 구독을 포함한 래퍼 Provider
+    return function ZustandI18nProvider({ children }) {
+        return React.createElement(BaseI18nProvider, {
+            children: React.createElement(LanguageSyncWrapper, { children })
+        });
+    };
+}
+/**
+ * Zustand 스토어와 i18n-core를 통합하는 Hook
+ *
+ * @param store - Zustand 스토어
+ * @returns { language, setLanguage, t } - i18n 훅과 동일한 인터페이스
+ *
+ * @example
+ * ```tsx
+ * import { useZustandI18n } from '@hua-labs/i18n-core-zustand';
+ * import { useAppStore } from './store/useAppStore';
+ *
+ * function MyComponent() {
+ *   const { language, setLanguage, t } = useZustandI18n(useAppStore);
+ *
+ *   return (
+ *     <div>
+ *       <p>{t('common:welcome')}</p>
+ *       <button onClick={() => setLanguage('en')}>English</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useZustandI18n(store) {
+    const adapter = React.useMemo(() => createZustandAdapter(store), [store]);
+    // 스토어의 언어 상태 구독
+    const language = store((state) => state.language);
+    // 언어 변경 함수
+    const setLanguage = React.useCallback((lang) => {
+        adapter.setLanguage(lang);
+    }, [adapter]);
+    return {
+        language,
+        setLanguage,
+        // useTranslation 훅은 별도로 import해서 사용
+        // 이 함수는 Zustand 스토어와의 통합만 제공
+    };
+}
+// 타입은 이미 위에서 export되었으므로 중복 export 제거
+//# sourceMappingURL=index.js.map

package/dist/index.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json ADDED Viewed

@@ -0,0 +1,57 @@
+{
+  "name": "@hua-labs/i18n-core-zustand",
+  "version": "1.0.0",
+  "description": "Zustand adapter for @hua-labs/i18n-core - Type-safe state management integration",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@hua-labs/i18n-core": "1.0.0"
+  },
+  "peerDependencies": {
+    "zustand": "^4.0.0",
+    "react": ">=16.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/react": "^19.2.7",
+    "typescript": "^5.9.3",
+    "zustand": "^4.0.0"
+  },
+  "keywords": [
+    "i18n",
+    "internationalization",
+    "zustand",
+    "state-management",
+    "adapter"
+  ],
+  "author": "HUA Labs",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/HUA-Labs/HUA-Labs-public.git"
+  },
+  "bugs": {
+    "url": "https://github.com/HUA-Labs/HUA-Labs-public/issues"
+  },
+  "homepage": "https://github.com/HUA-Labs/HUA-Labs-public#readme",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "test": "echo \"No tests defined\"",
+    "lint": "echo 'Skipping lint for hua-i18n-core-zustand'",
+    "type-check": "tsc --noEmit"
+  }
+}

package/src/index.ts ADDED Viewed

@@ -0,0 +1,347 @@
+/**
+ * @hua-labs/i18n-core-zustand - Zustand 어댑터
+ *
+ * Zustand 상태관리와 i18n-core를 타입 안전하게 통합하는 어댑터입니다.
+ *
+ * @example
+ * ```tsx
+ * import { createZustandI18n } from '@hua-labs/i18n-core-zustand';
+ * import { useAppStore } from './store/useAppStore';
+ *
+ * // Zustand 스토어에 language와 setLanguage가 있어야 함
+ * const I18nProvider = createZustandI18n(useAppStore, {
+ *   fallbackLanguage: 'en',
+ *   namespaces: ['common', 'navigation']
+ * });
+ *
+ * export default function Layout({ children }) {
+ *   return <I18nProvider>{children}</I18nProvider>;
+ * }
+ * ```
+ */
+import React from 'react';
+import { createCoreI18n, useTranslation } from '@hua-labs/i18n-core';
+import type { StoreApi, UseBoundStore } from 'zustand';
+/**
+ * Zustand 스토어에서 언어 관련 상태를 가져오는 인터페이스
+ */
+export interface ZustandLanguageStore {
+  language: string | 'ko' | 'en';
+  setLanguage: (lang: string | 'ko' | 'en') => void;
+}
+/**
+ * Zustand 스토어 어댑터 인터페이스
+ */
+export interface ZustandI18nAdapter {
+  getLanguage: () => string;
+  setLanguage: (lang: string) => void;
+  subscribe: (callback: (lang: string) => void) => () => void;
+}
+/**
+ * Zustand 스토어에서 어댑터 생성
+ */
+function createZustandAdapter(
+  store: UseBoundStore<StoreApi<ZustandLanguageStore>>
+): ZustandI18nAdapter {
+  return {
+    getLanguage: () => store.getState().language,
+    setLanguage: (lang: string) => {
+      const currentLang = store.getState().language;
+      if (currentLang !== lang) {
+        store.getState().setLanguage(lang);
+      }
+    },
+    subscribe: (callback: (lang: string) => void) => {
+      // Zustand의 subscribe를 사용하여 언어 변경 감지
+      let prevLanguage = store.getState().language;
+      return store.subscribe((state) => {
+        const currentLanguage = state.language;
+        if (currentLanguage !== prevLanguage) {
+          prevLanguage = currentLanguage;
+          callback(currentLanguage);
+        }
+      });
+    }
+  };
+}
+/**
+ * Zustand 스토어와 i18n-core를 통합하는 Provider 생성
+ *
+ * @param store - Zustand 스토어 (language와 setLanguage 메서드 필요)
+ * @param config - i18n 설정 (defaultLanguage는 스토어에서 가져옴)
+ * @returns I18nProvider 컴포넌트
+ *
+ * @example
+ * ```tsx
+ * import { createZustandI18n } from '@hua-labs/i18n-core-zustand';
+ * import { useAppStore } from './store/useAppStore';
+ *
+ * const I18nProvider = createZustandI18n(useAppStore, {
+ *   fallbackLanguage: 'en',
+ *   namespaces: ['common', 'navigation', 'footer'],
+ *   translationLoader: 'api',
+ *   debug: process.env.NODE_ENV === 'development'
+ * });
+ *
+ * export default function RootLayout({ children }) {
+ *   return <I18nProvider>{children}</I18nProvider>;
+ * }
+ * ```
+ */
+export interface ZustandI18nConfig {
+  defaultLanguage?: string; // SSR과 일치시키기 위한 초기 언어 (하이드레이션 에러 방지)
+  fallbackLanguage?: string;
+  namespaces?: string[];
+  debug?: boolean;
+  loadTranslations?: (language: string, namespace: string) => Promise<Record<string, string>>;
+  translationLoader?: 'api' | 'static' | 'custom';
+  translationApiPath?: string;
+  initialTranslations?: Record<string, Record<string, Record<string, string>>>;
+  autoLanguageSync?: boolean;
+}
+export function createZustandI18n(
+  store: UseBoundStore<StoreApi<ZustandLanguageStore>>,
+  config?: ZustandI18nConfig
+): React.ComponentType<{ children: React.ReactNode }> {
+  const adapter = createZustandAdapter(store);
+  // 하이드레이션 에러 방지: SSR과 동일한 초기 언어 사용
+  // config에 defaultLanguage가 있으면 사용, 없으면 'ko' (SSR 기본값과 일치)
+  // 하이드레이션 완료 후 저장된 언어로 자동 동기화됨
+  const initialLanguage = config?.defaultLanguage || 'ko';
+  const storeLanguage = adapter.getLanguage();
+  // createCoreI18n으로 기본 Provider 생성
+  const BaseI18nProvider = createCoreI18n({
+    ...config,
+    defaultLanguage: initialLanguage, // SSR과 동일한 초기 언어 사용
+    // Zustand 어댑터가 직접 언어 동기화 처리하므로 autoLanguageSync 비활성화
+    autoLanguageSync: false
+  });
+  // 언어 동기화 래퍼 컴포넌트 (Provider 내부에서만 사용)
+  // BaseI18nProvider가 I18nProvider를 렌더링하므로, 그 자식으로 들어가면 useTranslation 사용 가능
+  function LanguageSyncWrapper({ children: innerChildren }: { children: React.ReactNode }) {
+    const debug = config?.debug ?? false;
+    // useTranslation은 I18nProvider 내부에서만 사용 가능
+    // BaseI18nProvider가 I18nProvider를 렌더링하므로 여기서 사용 가능
+    const { setLanguage: setI18nLanguage, currentLanguage, isInitialized } = useTranslation();
+    // 하이드레이션 상태를 하나의 객체로 관리
+    interface HydrationState {
+      isComplete: boolean;
+      isInitialized: boolean;
+      previousStoreLanguage: string | null;
+      currentI18nLanguage: string;
+    }
+    const hydrationStateRef = React.useRef<HydrationState>({
+      isComplete: false,
+      isInitialized: false,
+      previousStoreLanguage: null,
+      currentI18nLanguage: currentLanguage,
+    });
+    // currentLanguage가 변경되면 상태 업데이트
+    React.useEffect(() => {
+      hydrationStateRef.current.currentI18nLanguage = currentLanguage;
+    }, [currentLanguage]);
+    // 하이드레이션 완료 감지 및 언어 동기화
+    React.useEffect(() => {
+      if (typeof window === 'undefined' || hydrationStateRef.current.isComplete) {
+        return;
+      }
+      const checkHydration = () => {
+        if (hydrationStateRef.current.isComplete) {
+          return;
+        }
+        hydrationStateRef.current.isComplete = true;
+        hydrationStateRef.current.isInitialized = isInitialized;
+        if (debug) {
+          console.log(`✅ [ZUSTAND-I18N] Hydration complete`);
+        }
+        // 하이드레이션 완료 후 저장된 언어로 동기화
+        if (isInitialized) {
+          const storeLanguage = store.getState().language;
+          const state = hydrationStateRef.current;
+          // initialLanguage와 다르고, 현재 i18n 언어와도 다를 때만 동기화
+          if (storeLanguage !== initialLanguage && storeLanguage !== state.currentI18nLanguage) {
+            if (debug) {
+              console.log(`🔄 [ZUSTAND-I18N] Hydration complete, syncing language: ${state.currentI18nLanguage} -> ${storeLanguage}`);
+            }
+            setI18nLanguage(storeLanguage);
+            state.previousStoreLanguage = storeLanguage;
+          } else {
+            if (debug) {
+              console.log(`⏭️ [ZUSTAND-I18N] Hydration complete, no sync needed (store: ${storeLanguage}, initial: ${initialLanguage}, current: ${state.currentI18nLanguage})`);
+            }
+            state.previousStoreLanguage = storeLanguage;
+          }
+        }
+      };
+      // 브라우저가 준비되면 하이드레이션 완료로 간주
+      const timeoutId = setTimeout(() => {
+        requestAnimationFrame(checkHydration);
+      }, 0);
+      return () => clearTimeout(timeoutId);
+    }, [isInitialized, setI18nLanguage, initialLanguage, debug]);
+    // 언어 동기화 함수 (재사용)
+    const syncLanguageFromStore = React.useCallback(() => {
+      const state = hydrationStateRef.current;
+      if (!state.isInitialized || !state.isComplete) {
+        return;
+      }
+      const storeLanguage = store.getState().language;
+      if (storeLanguage !== state.currentI18nLanguage && storeLanguage !== initialLanguage) {
+        if (debug) {
+          console.log(`🔄 [ZUSTAND-I18N] Syncing language from store: ${state.currentI18nLanguage} -> ${storeLanguage}`);
+        }
+        setI18nLanguage(storeLanguage);
+        state.previousStoreLanguage = storeLanguage;
+      }
+    }, [setI18nLanguage, initialLanguage, debug]);
+    // 언어 변경 구독 설정
+    React.useEffect(() => {
+      // Translator가 초기화된 후에만 동기화
+      if (!isInitialized) {
+        return;
+      }
+      const state = hydrationStateRef.current;
+      state.isInitialized = true;
+      // 초기 스토어 언어 설정
+      if (state.previousStoreLanguage === null) {
+        state.previousStoreLanguage = store.getState().language;
+      }
+      // Zustand 스토어 변경 감지
+      const unsubscribe = adapter.subscribe((newLanguage) => {
+        // 이전 언어와 다를 때만 처리
+        if (newLanguage !== state.previousStoreLanguage) {
+          state.previousStoreLanguage = newLanguage;
+          // 하이드레이션 완료 후에만 동기화
+          if (state.isComplete) {
+            // 현재 i18n 언어와 다를 때만 동기화 (무한 루프 방지)
+            if (newLanguage !== state.currentI18nLanguage) {
+              if (debug) {
+                console.log(`🔄 [ZUSTAND-I18N] Store language changed, syncing to i18n: ${state.currentI18nLanguage} -> ${newLanguage}`);
+              }
+              setI18nLanguage(newLanguage);
+            } else {
+              if (debug) {
+                console.log(`⏭️ [ZUSTAND-I18N] Store language changed but i18n already synced: ${newLanguage}`);
+              }
+            }
+          } else {
+            // 하이드레이션 완료 전에는 로그만 출력
+            if (debug) {
+              console.log(`⏳ [ZUSTAND-I18N] Store language changed but hydration not complete yet: ${newLanguage}`);
+            }
+          }
+        }
+      });
+      // 하이드레이션이 이미 완료되었다면 즉시 동기화
+      if (state.isComplete) {
+        const storeLanguage = store.getState().language;
+        // initialLanguage와 다르고, 현재 i18n 언어와도 다를 때만 동기화
+        if (storeLanguage !== initialLanguage && storeLanguage !== state.currentI18nLanguage) {
+          if (debug) {
+            console.log(`🔄 [ZUSTAND-I18N] Already hydrated, syncing language: ${state.currentI18nLanguage} -> ${storeLanguage}`);
+          }
+          setI18nLanguage(storeLanguage);
+          state.previousStoreLanguage = storeLanguage;
+        } else {
+          if (debug) {
+            console.log(`⏭️ [ZUSTAND-I18N] Already hydrated, no sync needed (store: ${storeLanguage}, initial: ${initialLanguage}, current: ${state.currentI18nLanguage})`);
+          }
+        }
+      }
+      return unsubscribe;
+    }, [isInitialized, setI18nLanguage, initialLanguage, debug]);
+    // 하이드레이션 완료 후 언어 동기화를 위한 별도 useEffect
+    // hydratedRef는 ref이므로 의존성으로 사용할 수 없음
+    // 대신 하이드레이션 완료 시점에 직접 syncLanguageFromStore 호출
+    return React.createElement(React.Fragment, null, innerChildren);
+  }
+  // Zustand 스토어 구독을 포함한 래퍼 Provider
+  return function ZustandI18nProvider({ children }: { children: React.ReactNode }) {
+    return React.createElement(BaseI18nProvider, {
+      children: React.createElement(LanguageSyncWrapper, { children })
+    });
+  };
+}
+/**
+ * Zustand 스토어와 i18n-core를 통합하는 Hook
+ *
+ * @param store - Zustand 스토어
+ * @returns { language, setLanguage, t } - i18n 훅과 동일한 인터페이스
+ *
+ * @example
+ * ```tsx
+ * import { useZustandI18n } from '@hua-labs/i18n-core-zustand';
+ * import { useAppStore } from './store/useAppStore';
+ *
+ * function MyComponent() {
+ *   const { language, setLanguage, t } = useZustandI18n(useAppStore);
+ *
+ *   return (
+ *     <div>
+ *       <p>{t('common:welcome')}</p>
+ *       <button onClick={() => setLanguage('en')}>English</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useZustandI18n(
+  store: UseBoundStore<StoreApi<ZustandLanguageStore>>
+) {
+  const adapter = React.useMemo(() => createZustandAdapter(store), [store]);
+  // 스토어의 언어 상태 구독
+  const language = store((state) => state.language);
+  // 언어 변경 함수
+  const setLanguage = React.useCallback(
+    (lang: string) => {
+      adapter.setLanguage(lang);
+    },
+    [adapter]
+  );
+  return {
+    language,
+    setLanguage,
+    // useTranslation 훅은 별도로 import해서 사용
+    // 이 함수는 Zustand 스토어와의 통합만 제공
+  };
+}
+// 타입은 이미 위에서 export되었으므로 중복 export 제거