@hua-labs/i18n-core-zustand 1.0.0 → 2.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.
- package/LICENSE +20 -20
- package/README.md +249 -249
- package/dist/index.d.ts +43 -6
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +28 -0
- package/dist/index.js.map +1 -1
- package/package.json +2 -2
- package/src/index.ts +399 -347
package/LICENSE
CHANGED
|
@@ -1,21 +1,21 @@
|
|
|
1
|
-
MIT License
|
|
2
|
-
|
|
3
|
-
Copyright (c) 2024 HUA Labs Team
|
|
4
|
-
|
|
5
|
-
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
-
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
-
in the Software without restriction, including without limitation the rights
|
|
8
|
-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
-
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
-
furnished to do so, subject to the following conditions:
|
|
11
|
-
|
|
12
|
-
The above copyright notice and this permission notice shall be included in all
|
|
13
|
-
copies or substantial portions of the Software.
|
|
14
|
-
|
|
15
|
-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024 HUA Labs Team
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
21
|
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,249 +1,249 @@
|
|
|
1
|
-
# @hua-labs/i18n-core-zustand
|
|
2
|
-
|
|
3
|
-
Type-safe adapter package for integrating Zustand state management with `@hua-labs/i18n-core`.
|
|
4
|
-
|
|
5
|
-
## Installation
|
|
6
|
-
|
|
7
|
-
```bash
|
|
8
|
-
pnpm add @hua-labs/i18n-core-zustand zustand
|
|
9
|
-
# or
|
|
10
|
-
npm install @hua-labs/i18n-core-zustand zustand
|
|
11
|
-
# or
|
|
12
|
-
yarn add @hua-labs/i18n-core-zustand zustand
|
|
13
|
-
```
|
|
14
|
-
|
|
15
|
-
## Requirements
|
|
16
|
-
|
|
17
|
-
- Your Zustand store must have `language: string` and `setLanguage: (lang: string) => void`.
|
|
18
|
-
|
|
19
|
-
## Usage
|
|
20
|
-
|
|
21
|
-
### 1. Basic Usage (Create Provider)
|
|
22
|
-
|
|
23
|
-
```tsx
|
|
24
|
-
// lib/i18n-config.ts
|
|
25
|
-
import { createZustandI18n } from '@hua-labs/i18n-core-zustand';
|
|
26
|
-
import { useAppStore } from '../store/useAppStore';
|
|
27
|
-
|
|
28
|
-
export const I18nProvider = createZustandI18n(useAppStore, {
|
|
29
|
-
fallbackLanguage: 'en',
|
|
30
|
-
namespaces: ['common', 'navigation', 'footer'],
|
|
31
|
-
translationLoader: 'api',
|
|
32
|
-
translationApiPath: '/api/translations',
|
|
33
|
-
defaultLanguage: 'ko', // SSR initial language (prevents hydration errors)
|
|
34
|
-
debug: process.env.NODE_ENV === 'development'
|
|
35
|
-
});
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
```tsx
|
|
39
|
-
// app/layout.tsx
|
|
40
|
-
import { I18nProvider } from './lib/i18n-config';
|
|
41
|
-
|
|
42
|
-
export default function RootLayout({ children }) {
|
|
43
|
-
return (
|
|
44
|
-
<html>
|
|
45
|
-
<body>
|
|
46
|
-
<I18nProvider>{children}</I18nProvider>
|
|
47
|
-
</body>
|
|
48
|
-
</html>
|
|
49
|
-
);
|
|
50
|
-
}
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
### 2. Zustand Store Example
|
|
54
|
-
|
|
55
|
-
```tsx
|
|
56
|
-
// store/useAppStore.ts
|
|
57
|
-
import { create } from 'zustand';
|
|
58
|
-
import { persist } from 'zustand/middleware';
|
|
59
|
-
|
|
60
|
-
interface AppState {
|
|
61
|
-
language: 'ko' | 'en';
|
|
62
|
-
setLanguage: (lang: 'ko' | 'en') => void;
|
|
63
|
-
}
|
|
64
|
-
|
|
65
|
-
export const useAppStore = create<AppState>()(
|
|
66
|
-
persist(
|
|
67
|
-
(set) => ({
|
|
68
|
-
language: 'ko',
|
|
69
|
-
setLanguage: (lang) => set({ language: lang }),
|
|
70
|
-
}),
|
|
71
|
-
{
|
|
72
|
-
name: 'app-storage',
|
|
73
|
-
partialize: (state) => ({ language: state.language }),
|
|
74
|
-
}
|
|
75
|
-
)
|
|
76
|
-
);
|
|
77
|
-
```
|
|
78
|
-
|
|
79
|
-
### 3. Using Translations
|
|
80
|
-
|
|
81
|
-
```tsx
|
|
82
|
-
// components/MyComponent.tsx
|
|
83
|
-
import { useTranslation } from '@hua-labs/i18n-core';
|
|
84
|
-
import { useAppStore } from '../store/useAppStore';
|
|
85
|
-
|
|
86
|
-
export default function MyComponent() {
|
|
87
|
-
const { t } = useTranslation();
|
|
88
|
-
const { language, setLanguage } = useAppStore();
|
|
89
|
-
|
|
90
|
-
return (
|
|
91
|
-
<div>
|
|
92
|
-
<h1>{t('common:welcome')}</h1>
|
|
93
|
-
<button onClick={() => setLanguage(language === 'ko' ? 'en' : 'ko')}>
|
|
94
|
-
{language === 'ko' ? 'English' : '한국어'}
|
|
95
|
-
</button>
|
|
96
|
-
</div>
|
|
97
|
-
);
|
|
98
|
-
}
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
### 4. Using with SSR
|
|
102
|
-
|
|
103
|
-
```tsx
|
|
104
|
-
// app/layout.tsx (Server Component)
|
|
105
|
-
import { loadSSRTranslations } from './lib/ssr-translations';
|
|
106
|
-
import { createZustandI18n } from '@hua-labs/i18n-core-zustand';
|
|
107
|
-
import { useAppStore } from './store/useAppStore';
|
|
108
|
-
|
|
109
|
-
export default async function RootLayout({ children }) {
|
|
110
|
-
// Load translations from SSR
|
|
111
|
-
const ssrTranslations = await loadSSRTranslations('ko');
|
|
112
|
-
|
|
113
|
-
const I18nProvider = createZustandI18n(useAppStore, {
|
|
114
|
-
fallbackLanguage: 'en',
|
|
115
|
-
namespaces: ['common', 'navigation', 'footer'],
|
|
116
|
-
translationLoader: 'api',
|
|
117
|
-
translationApiPath: '/api/translations',
|
|
118
|
-
defaultLanguage: 'ko', // Same initial language as SSR
|
|
119
|
-
initialTranslations: ssrTranslations, // Pass SSR translations
|
|
120
|
-
debug: process.env.NODE_ENV === 'development'
|
|
121
|
-
});
|
|
122
|
-
|
|
123
|
-
return (
|
|
124
|
-
<html lang="ko">
|
|
125
|
-
<body>
|
|
126
|
-
<I18nProvider>{children}</I18nProvider>
|
|
127
|
-
</body>
|
|
128
|
-
</html>
|
|
129
|
-
);
|
|
130
|
-
}
|
|
131
|
-
```
|
|
132
|
-
|
|
133
|
-
## API
|
|
134
|
-
|
|
135
|
-
### `createZustandI18n(store, config)`
|
|
136
|
-
|
|
137
|
-
Creates a Provider that integrates Zustand store with i18n-core.
|
|
138
|
-
|
|
139
|
-
**Parameters:**
|
|
140
|
-
- `store`: Zustand store (must have `language` and `setLanguage` methods)
|
|
141
|
-
- `config`: i18n configuration (same as `I18nConfig` except `defaultLanguage`)
|
|
142
|
-
|
|
143
|
-
**Returns:**
|
|
144
|
-
- React Provider component
|
|
145
|
-
|
|
146
|
-
**Configuration Options:**
|
|
147
|
-
|
|
148
|
-
```ts
|
|
149
|
-
interface ZustandI18nConfig {
|
|
150
|
-
// Initial language to match SSR (prevents hydration errors)
|
|
151
|
-
defaultLanguage?: string;
|
|
152
|
-
|
|
153
|
-
// Fallback language
|
|
154
|
-
fallbackLanguage?: string;
|
|
155
|
-
|
|
156
|
-
// Namespace list
|
|
157
|
-
namespaces?: string[];
|
|
158
|
-
|
|
159
|
-
// Debug mode
|
|
160
|
-
debug?: boolean;
|
|
161
|
-
|
|
162
|
-
// Custom translation loader
|
|
163
|
-
loadTranslations?: (language: string, namespace: string) => Promise<Record<string, string>>;
|
|
164
|
-
|
|
165
|
-
// Translation loader type
|
|
166
|
-
translationLoader?: 'api' | 'static' | 'custom';
|
|
167
|
-
|
|
168
|
-
// API path (when translationLoader is 'api')
|
|
169
|
-
translationApiPath?: string;
|
|
170
|
-
|
|
171
|
-
// SSR initial translation data
|
|
172
|
-
initialTranslations?: Record<string, Record<string, Record<string, string>>>;
|
|
173
|
-
|
|
174
|
-
// Auto language sync (always false in this package)
|
|
175
|
-
autoLanguageSync?: boolean;
|
|
176
|
-
}
|
|
177
|
-
```
|
|
178
|
-
|
|
179
|
-
### `useZustandI18n(store)`
|
|
180
|
-
|
|
181
|
-
Provides i18n hook integrated with Zustand store.
|
|
182
|
-
|
|
183
|
-
**Parameters:**
|
|
184
|
-
- `store`: Zustand store
|
|
185
|
-
|
|
186
|
-
**Returns:**
|
|
187
|
-
- `{ language, setLanguage }`: Language state and change function
|
|
188
|
-
|
|
189
|
-
**Note:** Use `useTranslation` hook for actual translations:
|
|
190
|
-
|
|
191
|
-
```tsx
|
|
192
|
-
import { useTranslation } from '@hua-labs/i18n-core';
|
|
193
|
-
import { useZustandI18n } from '@hua-labs/i18n-core-zustand';
|
|
194
|
-
import { useAppStore } from './store/useAppStore';
|
|
195
|
-
|
|
196
|
-
function MyComponent() {
|
|
197
|
-
const { t } = useTranslation(); // Translation function
|
|
198
|
-
const { language, setLanguage } = useZustandI18n(useAppStore); // Language state
|
|
199
|
-
|
|
200
|
-
return (
|
|
201
|
-
<div>
|
|
202
|
-
<p>{t('common:welcome')}</p>
|
|
203
|
-
<button onClick={() => setLanguage('en')}>English</button>
|
|
204
|
-
</div>
|
|
205
|
-
);
|
|
206
|
-
}
|
|
207
|
-
```
|
|
208
|
-
|
|
209
|
-
## Features
|
|
210
|
-
|
|
211
|
-
- **Type-safe**: Full TypeScript support
|
|
212
|
-
- **Minimal dependencies**: Only Zustand as peer dependency
|
|
213
|
-
- **Auto synchronization**: Automatically syncs Zustand store changes to i18n
|
|
214
|
-
- **Unidirectional data flow**: Zustand store is the source of truth
|
|
215
|
-
- **SSR compatible**: Language syncs after hydration completes (prevents hydration errors)
|
|
216
|
-
- **Circular reference prevention**: Safe language synchronization mechanism
|
|
217
|
-
|
|
218
|
-
## How It Works
|
|
219
|
-
|
|
220
|
-
1. **Initialization**: `createZustandI18n` wraps `createCoreI18n` to create the base Provider.
|
|
221
|
-
2. **Language synchronization**: Detects Zustand store language changes and automatically syncs to i18n.
|
|
222
|
-
3. **Hydration**: Only syncs language after hydration completes to prevent SSR/client hydration errors.
|
|
223
|
-
4. **Circular reference prevention**: Uses `useRef` to prevent infinite loops and maintains unidirectional data flow.
|
|
224
|
-
|
|
225
|
-
## Caveats
|
|
226
|
-
|
|
227
|
-
1. **Zustand store structure**: Store must have `language` and `setLanguage`.
|
|
228
|
-
2. **autoLanguageSync**: This package automatically disables `autoLanguageSync` (Zustand adapter handles it directly).
|
|
229
|
-
3. **Language changes**: Language changes must be made through Zustand store's `setLanguage`.
|
|
230
|
-
4. **SSR initial language**: Use `defaultLanguage` option to set the same initial language as SSR (prevents hydration errors).
|
|
231
|
-
5. **Hydration**: Zustand store language only syncs to i18n after hydration completes.
|
|
232
|
-
|
|
233
|
-
## Examples
|
|
234
|
-
|
|
235
|
-
- **[CodeSandbox Template](../../examples/codesandbox-template/)** - Quick start with Zustand
|
|
236
|
-
- **[Next.js Example](../../examples/next-app-router-example/)** - Complete Next.js example
|
|
237
|
-
|
|
238
|
-
## Documentation
|
|
239
|
-
|
|
240
|
-
- [Hydration Guide](./docs/HYDRATION.md) - Hydration process and troubleshooting
|
|
241
|
-
|
|
242
|
-
## Related Packages
|
|
243
|
-
|
|
244
|
-
- `@hua-labs/i18n-core`: Core i18n library
|
|
245
|
-
- `@hua-labs/i18n-loaders`: Production-ready loaders and caching utilities
|
|
246
|
-
|
|
247
|
-
## License
|
|
248
|
-
|
|
249
|
-
MIT
|
|
1
|
+
# @hua-labs/i18n-core-zustand
|
|
2
|
+
|
|
3
|
+
Type-safe adapter package for integrating Zustand state management with `@hua-labs/i18n-core`.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
pnpm add @hua-labs/i18n-core-zustand zustand
|
|
9
|
+
# or
|
|
10
|
+
npm install @hua-labs/i18n-core-zustand zustand
|
|
11
|
+
# or
|
|
12
|
+
yarn add @hua-labs/i18n-core-zustand zustand
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Requirements
|
|
16
|
+
|
|
17
|
+
- Your Zustand store must have `language: string` and `setLanguage: (lang: string) => void`.
|
|
18
|
+
|
|
19
|
+
## Usage
|
|
20
|
+
|
|
21
|
+
### 1. Basic Usage (Create Provider)
|
|
22
|
+
|
|
23
|
+
```tsx
|
|
24
|
+
// lib/i18n-config.ts
|
|
25
|
+
import { createZustandI18n } from '@hua-labs/i18n-core-zustand';
|
|
26
|
+
import { useAppStore } from '../store/useAppStore';
|
|
27
|
+
|
|
28
|
+
export const I18nProvider = createZustandI18n(useAppStore, {
|
|
29
|
+
fallbackLanguage: 'en',
|
|
30
|
+
namespaces: ['common', 'navigation', 'footer'],
|
|
31
|
+
translationLoader: 'api',
|
|
32
|
+
translationApiPath: '/api/translations',
|
|
33
|
+
defaultLanguage: 'ko', // SSR initial language (prevents hydration errors)
|
|
34
|
+
debug: process.env.NODE_ENV === 'development'
|
|
35
|
+
});
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
```tsx
|
|
39
|
+
// app/layout.tsx
|
|
40
|
+
import { I18nProvider } from './lib/i18n-config';
|
|
41
|
+
|
|
42
|
+
export default function RootLayout({ children }) {
|
|
43
|
+
return (
|
|
44
|
+
<html>
|
|
45
|
+
<body>
|
|
46
|
+
<I18nProvider>{children}</I18nProvider>
|
|
47
|
+
</body>
|
|
48
|
+
</html>
|
|
49
|
+
);
|
|
50
|
+
}
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
### 2. Zustand Store Example
|
|
54
|
+
|
|
55
|
+
```tsx
|
|
56
|
+
// store/useAppStore.ts
|
|
57
|
+
import { create } from 'zustand';
|
|
58
|
+
import { persist } from 'zustand/middleware';
|
|
59
|
+
|
|
60
|
+
interface AppState {
|
|
61
|
+
language: 'ko' | 'en';
|
|
62
|
+
setLanguage: (lang: 'ko' | 'en') => void;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
export const useAppStore = create<AppState>()(
|
|
66
|
+
persist(
|
|
67
|
+
(set) => ({
|
|
68
|
+
language: 'ko',
|
|
69
|
+
setLanguage: (lang) => set({ language: lang }),
|
|
70
|
+
}),
|
|
71
|
+
{
|
|
72
|
+
name: 'app-storage',
|
|
73
|
+
partialize: (state) => ({ language: state.language }),
|
|
74
|
+
}
|
|
75
|
+
)
|
|
76
|
+
);
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
### 3. Using Translations
|
|
80
|
+
|
|
81
|
+
```tsx
|
|
82
|
+
// components/MyComponent.tsx
|
|
83
|
+
import { useTranslation } from '@hua-labs/i18n-core';
|
|
84
|
+
import { useAppStore } from '../store/useAppStore';
|
|
85
|
+
|
|
86
|
+
export default function MyComponent() {
|
|
87
|
+
const { t } = useTranslation();
|
|
88
|
+
const { language, setLanguage } = useAppStore();
|
|
89
|
+
|
|
90
|
+
return (
|
|
91
|
+
<div>
|
|
92
|
+
<h1>{t('common:welcome')}</h1>
|
|
93
|
+
<button onClick={() => setLanguage(language === 'ko' ? 'en' : 'ko')}>
|
|
94
|
+
{language === 'ko' ? 'English' : '한국어'}
|
|
95
|
+
</button>
|
|
96
|
+
</div>
|
|
97
|
+
);
|
|
98
|
+
}
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
### 4. Using with SSR
|
|
102
|
+
|
|
103
|
+
```tsx
|
|
104
|
+
// app/layout.tsx (Server Component)
|
|
105
|
+
import { loadSSRTranslations } from './lib/ssr-translations';
|
|
106
|
+
import { createZustandI18n } from '@hua-labs/i18n-core-zustand';
|
|
107
|
+
import { useAppStore } from './store/useAppStore';
|
|
108
|
+
|
|
109
|
+
export default async function RootLayout({ children }) {
|
|
110
|
+
// Load translations from SSR
|
|
111
|
+
const ssrTranslations = await loadSSRTranslations('ko');
|
|
112
|
+
|
|
113
|
+
const I18nProvider = createZustandI18n(useAppStore, {
|
|
114
|
+
fallbackLanguage: 'en',
|
|
115
|
+
namespaces: ['common', 'navigation', 'footer'],
|
|
116
|
+
translationLoader: 'api',
|
|
117
|
+
translationApiPath: '/api/translations',
|
|
118
|
+
defaultLanguage: 'ko', // Same initial language as SSR
|
|
119
|
+
initialTranslations: ssrTranslations, // Pass SSR translations
|
|
120
|
+
debug: process.env.NODE_ENV === 'development'
|
|
121
|
+
});
|
|
122
|
+
|
|
123
|
+
return (
|
|
124
|
+
<html lang="ko">
|
|
125
|
+
<body>
|
|
126
|
+
<I18nProvider>{children}</I18nProvider>
|
|
127
|
+
</body>
|
|
128
|
+
</html>
|
|
129
|
+
);
|
|
130
|
+
}
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
## API
|
|
134
|
+
|
|
135
|
+
### `createZustandI18n(store, config)`
|
|
136
|
+
|
|
137
|
+
Creates a Provider that integrates Zustand store with i18n-core.
|
|
138
|
+
|
|
139
|
+
**Parameters:**
|
|
140
|
+
- `store`: Zustand store (must have `language` and `setLanguage` methods)
|
|
141
|
+
- `config`: i18n configuration (same as `I18nConfig` except `defaultLanguage`)
|
|
142
|
+
|
|
143
|
+
**Returns:**
|
|
144
|
+
- React Provider component
|
|
145
|
+
|
|
146
|
+
**Configuration Options:**
|
|
147
|
+
|
|
148
|
+
```ts
|
|
149
|
+
interface ZustandI18nConfig {
|
|
150
|
+
// Initial language to match SSR (prevents hydration errors)
|
|
151
|
+
defaultLanguage?: string;
|
|
152
|
+
|
|
153
|
+
// Fallback language
|
|
154
|
+
fallbackLanguage?: string;
|
|
155
|
+
|
|
156
|
+
// Namespace list
|
|
157
|
+
namespaces?: string[];
|
|
158
|
+
|
|
159
|
+
// Debug mode
|
|
160
|
+
debug?: boolean;
|
|
161
|
+
|
|
162
|
+
// Custom translation loader
|
|
163
|
+
loadTranslations?: (language: string, namespace: string) => Promise<Record<string, string>>;
|
|
164
|
+
|
|
165
|
+
// Translation loader type
|
|
166
|
+
translationLoader?: 'api' | 'static' | 'custom';
|
|
167
|
+
|
|
168
|
+
// API path (when translationLoader is 'api')
|
|
169
|
+
translationApiPath?: string;
|
|
170
|
+
|
|
171
|
+
// SSR initial translation data
|
|
172
|
+
initialTranslations?: Record<string, Record<string, Record<string, string>>>;
|
|
173
|
+
|
|
174
|
+
// Auto language sync (always false in this package)
|
|
175
|
+
autoLanguageSync?: boolean;
|
|
176
|
+
}
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
### `useZustandI18n(store)`
|
|
180
|
+
|
|
181
|
+
Provides i18n hook integrated with Zustand store.
|
|
182
|
+
|
|
183
|
+
**Parameters:**
|
|
184
|
+
- `store`: Zustand store
|
|
185
|
+
|
|
186
|
+
**Returns:**
|
|
187
|
+
- `{ language, setLanguage }`: Language state and change function
|
|
188
|
+
|
|
189
|
+
**Note:** Use `useTranslation` hook for actual translations:
|
|
190
|
+
|
|
191
|
+
```tsx
|
|
192
|
+
import { useTranslation } from '@hua-labs/i18n-core';
|
|
193
|
+
import { useZustandI18n } from '@hua-labs/i18n-core-zustand';
|
|
194
|
+
import { useAppStore } from './store/useAppStore';
|
|
195
|
+
|
|
196
|
+
function MyComponent() {
|
|
197
|
+
const { t } = useTranslation(); // Translation function
|
|
198
|
+
const { language, setLanguage } = useZustandI18n(useAppStore); // Language state
|
|
199
|
+
|
|
200
|
+
return (
|
|
201
|
+
<div>
|
|
202
|
+
<p>{t('common:welcome')}</p>
|
|
203
|
+
<button onClick={() => setLanguage('en')}>English</button>
|
|
204
|
+
</div>
|
|
205
|
+
);
|
|
206
|
+
}
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
## Features
|
|
210
|
+
|
|
211
|
+
- **Type-safe**: Full TypeScript support
|
|
212
|
+
- **Minimal dependencies**: Only Zustand as peer dependency
|
|
213
|
+
- **Auto synchronization**: Automatically syncs Zustand store changes to i18n
|
|
214
|
+
- **Unidirectional data flow**: Zustand store is the source of truth
|
|
215
|
+
- **SSR compatible**: Language syncs after hydration completes (prevents hydration errors)
|
|
216
|
+
- **Circular reference prevention**: Safe language synchronization mechanism
|
|
217
|
+
|
|
218
|
+
## How It Works
|
|
219
|
+
|
|
220
|
+
1. **Initialization**: `createZustandI18n` wraps `createCoreI18n` to create the base Provider.
|
|
221
|
+
2. **Language synchronization**: Detects Zustand store language changes and automatically syncs to i18n.
|
|
222
|
+
3. **Hydration**: Only syncs language after hydration completes to prevent SSR/client hydration errors.
|
|
223
|
+
4. **Circular reference prevention**: Uses `useRef` to prevent infinite loops and maintains unidirectional data flow.
|
|
224
|
+
|
|
225
|
+
## Caveats
|
|
226
|
+
|
|
227
|
+
1. **Zustand store structure**: Store must have `language` and `setLanguage`.
|
|
228
|
+
2. **autoLanguageSync**: This package automatically disables `autoLanguageSync` (Zustand adapter handles it directly).
|
|
229
|
+
3. **Language changes**: Language changes must be made through Zustand store's `setLanguage`.
|
|
230
|
+
4. **SSR initial language**: Use `defaultLanguage` option to set the same initial language as SSR (prevents hydration errors).
|
|
231
|
+
5. **Hydration**: Zustand store language only syncs to i18n after hydration completes.
|
|
232
|
+
|
|
233
|
+
## Examples
|
|
234
|
+
|
|
235
|
+
- **[CodeSandbox Template](../../examples/codesandbox-template/)** - Quick start with Zustand
|
|
236
|
+
- **[Next.js Example](../../examples/next-app-router-example/)** - Complete Next.js example
|
|
237
|
+
|
|
238
|
+
## Documentation
|
|
239
|
+
|
|
240
|
+
- [Hydration Guide](./docs/HYDRATION.md) - Hydration process and troubleshooting
|
|
241
|
+
|
|
242
|
+
## Related Packages
|
|
243
|
+
|
|
244
|
+
- `@hua-labs/i18n-core`: Core i18n library
|
|
245
|
+
- `@hua-labs/i18n-loaders`: Production-ready loaders and caching utilities
|
|
246
|
+
|
|
247
|
+
## License
|
|
248
|
+
|
|
249
|
+
MIT
|
package/dist/index.d.ts
CHANGED
|
@@ -21,12 +21,28 @@
|
|
|
21
21
|
*/
|
|
22
22
|
import React from 'react';
|
|
23
23
|
import type { StoreApi, UseBoundStore } from 'zustand';
|
|
24
|
+
/**
|
|
25
|
+
* 지원되는 언어 코드 타입
|
|
26
|
+
* ISO 639-1 표준 언어 코드
|
|
27
|
+
*/
|
|
28
|
+
export type SupportedLanguage = 'ko' | 'en' | 'ja';
|
|
24
29
|
/**
|
|
25
30
|
* Zustand 스토어에서 언어 관련 상태를 가져오는 인터페이스
|
|
31
|
+
*
|
|
32
|
+
* @template L - 언어 코드 타입 (기본값: SupportedLanguage | string)
|
|
33
|
+
*
|
|
34
|
+
* @example
|
|
35
|
+
* ```typescript
|
|
36
|
+
* // 기본 사용 (모든 언어 코드 허용)
|
|
37
|
+
* interface MyStore extends ZustandLanguageStore {}
|
|
38
|
+
*
|
|
39
|
+
* // 특정 언어만 허용
|
|
40
|
+
* interface MyStore extends ZustandLanguageStore<'ko' | 'en'> {}
|
|
41
|
+
* ```
|
|
26
42
|
*/
|
|
27
|
-
export interface ZustandLanguageStore {
|
|
28
|
-
language:
|
|
29
|
-
setLanguage: (lang:
|
|
43
|
+
export interface ZustandLanguageStore<L extends string = SupportedLanguage | string> {
|
|
44
|
+
language: L;
|
|
45
|
+
setLanguage: (lang: L) => void;
|
|
30
46
|
}
|
|
31
47
|
/**
|
|
32
48
|
* Zustand 스토어 어댑터 인터페이스
|
|
@@ -70,8 +86,22 @@ export interface ZustandI18nConfig {
|
|
|
70
86
|
translationApiPath?: string;
|
|
71
87
|
initialTranslations?: Record<string, Record<string, Record<string, string>>>;
|
|
72
88
|
autoLanguageSync?: boolean;
|
|
89
|
+
/**
|
|
90
|
+
* document.documentElement.lang 자동 업데이트 여부
|
|
91
|
+
* 기본값: false (사용자가 직접 관리)
|
|
92
|
+
* true로 설정하면 언어 변경 시 자동으로 html[lang] 속성 업데이트
|
|
93
|
+
*/
|
|
94
|
+
autoUpdateHtmlLang?: boolean;
|
|
73
95
|
}
|
|
74
|
-
|
|
96
|
+
/**
|
|
97
|
+
* Zustand 스토어와 i18n-core를 통합하는 Provider 생성
|
|
98
|
+
*
|
|
99
|
+
* @template L - 언어 코드 타입
|
|
100
|
+
* @param store - Zustand 스토어 (language와 setLanguage 메서드 필요)
|
|
101
|
+
* @param config - i18n 설정
|
|
102
|
+
* @returns I18nProvider 컴포넌트
|
|
103
|
+
*/
|
|
104
|
+
export declare function createZustandI18n<L extends string = SupportedLanguage | string>(store: UseBoundStore<StoreApi<ZustandLanguageStore<L>>>, config?: ZustandI18nConfig): React.ComponentType<{
|
|
75
105
|
children: React.ReactNode;
|
|
76
106
|
}>;
|
|
77
107
|
/**
|
|
@@ -97,8 +127,15 @@ export declare function createZustandI18n(store: UseBoundStore<StoreApi<ZustandL
|
|
|
97
127
|
* }
|
|
98
128
|
* ```
|
|
99
129
|
*/
|
|
100
|
-
|
|
101
|
-
|
|
130
|
+
/**
|
|
131
|
+
* Zustand 스토어와 i18n-core를 통합하는 Hook
|
|
132
|
+
*
|
|
133
|
+
* @template L - 언어 코드 타입
|
|
134
|
+
* @param store - Zustand 스토어
|
|
135
|
+
* @returns { language, setLanguage } - 언어 상태 및 변경 함수
|
|
136
|
+
*/
|
|
137
|
+
export declare function useZustandI18n<L extends string = SupportedLanguage | string>(store: UseBoundStore<StoreApi<ZustandLanguageStore<L>>>): {
|
|
138
|
+
language: L;
|
|
102
139
|
setLanguage: (lang: string) => void;
|
|
103
140
|
};
|
|
104
141
|
//# sourceMappingURL=index.d.ts.map
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
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
|
|
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;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAEnD;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC,SAAS,MAAM,GAAG,iBAAiB,GAAG,MAAM;IACjF,QAAQ,EAAE,CAAC,CAAC;IACZ,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;CAChC;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;AAkCD;;;;;;;;;;;;;;;;;;;;;;;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;IAC3B;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,GAAG,iBAAiB,GAAG,MAAM,EAC7E,KAAK,EAAE,aAAa,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC,EACvD,MAAM,CAAC,EAAE,iBAAiB,GACzB,KAAK,CAAC,aAAa,CAAC;IAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAAE,CAAC,CAoMpD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,GAAG,iBAAiB,GAAG,MAAM,EAC1E,KAAK,EAAE,aAAa,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC;;wBAS9C,MAAM;EAYhB"}
|