11# hua-i18n-sdk
22
3- > ** v1.1 .0** - Simple and powerful internationalization SDK for React applications
3+ > ** v1.2 .0** - Simple and powerful internationalization SDK for React applications
44
55[ ![ npm version] ( https://badge.fury.io/js/hua-i18n-sdk.svg )] ( https://badge.fury.io/js/hua-i18n-sdk )
66[ ![ License: MIT] ( https://img.shields.io/badge/License-MIT-yellow.svg )] ( https://opensource.org/licenses/MIT )
77[ ![ TypeScript] ( https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white )] ( https://www.typescriptlang.org/ )
8+ [ ![ GitHub stars] ( https://img.shields.io/github/stars/HUA-Labs/i18n-sdk?style=social )] ( https://github.com/HUA-Labs/i18n-sdk )
9+
10+ ** ⭐ If this project helped you, please give it a star!**
811
912## Key Features
1013
1114- ** Simple API** : Intuitive and easy-to-use interface
12- - ** Type Safety** : Full TypeScript support with type safety
15+ - ** Beginner-friendly** : One-line setup with ` withDefaultConfig() `
16+ - ** Type Safety** : Full TypeScript support
1317- ** SSR Support** : Perfect compatibility with Next.js server components
14- - ** Robust Error Handling** : Automatic retry, recovery strategies, user-friendly messages
18+ - ** Robust Error Handling** : Auto- retry, recovery strategies, user-friendly messages
1519- ** Lightweight Bundle** : Optimized size with tree-shaking support
1620- ** Real-time Language Switching** : Dynamic language switching support
17- - ** Developer Friendly ** : Debug mode, missing key display, detailed logging
21+ - ** Developer-friendly ** : Debug mode, missing key display, detailed logging
1822
1923## Installation
2024
@@ -28,17 +32,87 @@ pnpm add hua-i18n-sdk
2832
2933## Quick Start
3034
31- ### 1. Basic Configuration
35+ ### 🚀 For Beginners (Recommended) - Easy Entry Point
36+
37+ ``` tsx
38+ // Beginner-friendly entry point - start immediately without complex configuration!
39+ import { withDefaultConfig , useTranslation } from ' hua-i18n-sdk/easy' ;
40+
41+ // One line setup! Start with default configuration
42+ export const I18nProvider = withDefaultConfig ();
43+
44+ function App() {
45+ return (
46+ <I18nProvider >
47+ <MyComponent />
48+ </I18nProvider >
49+ );
50+ }
51+
52+ function MyComponent() {
53+ const { t, tWithParams } = useTranslation ();
54+
55+ return (
56+ <div >
57+ <h1 >{ t (' common.welcome' )} </h1 >
58+ <p >{ tWithParams (' common.greeting' , { name: ' John' })} </p >
59+ </div >
60+ );
61+ }
62+ ```
63+
64+ ### 🚀 For Beginners (Recommended) - Default Entry Point
65+
66+ ``` tsx
67+ import { withDefaultConfig , useTranslation } from ' hua-i18n-sdk' ;
68+
69+ // One line setup! Start with default configuration
70+ export const I18nProvider = withDefaultConfig ();
71+
72+ function App() {
73+ return (
74+ <I18nProvider >
75+ <MyComponent />
76+ </I18nProvider >
77+ );
78+ }
79+
80+ function MyComponent() {
81+ const { t, tWithParams } = useTranslation ();
82+
83+ return (
84+ <div >
85+ <h1 >{ t (' common.welcome' )} </h1 >
86+ <p >{ tWithParams (' common.greeting' , { name: ' John' })} </p >
87+ </div >
88+ );
89+ }
90+ ```
91+
92+ ### ⚙️ For Intermediate Users (Partial Customization)
93+
94+ ``` tsx
95+ import { withDefaultConfig } from ' hua-i18n-sdk' ;
96+
97+ // Customize only what you need
98+ export const I18nProvider = withDefaultConfig ({
99+ defaultLanguage: ' en' ,
100+ namespaces: [' common' , ' auth' ],
101+ debug: true ,
102+ });
103+ ```
104+
105+ ### 🔧 For Advanced Users (Full Customization)
32106
33107``` tsx
34108import { I18nProvider , useTranslation , createI18nConfig } from ' hua-i18n-sdk' ;
35109
36110const i18nConfig = createI18nConfig ({
37- defaultLanguage: ' en ' ,
38- fallbackLanguage: ' ko ' ,
111+ defaultLanguage: ' ko ' ,
112+ fallbackLanguage: ' en ' ,
39113 supportedLanguages: [
40- { code: ' en' , name: ' English' , nativeName: ' English' },
41114 { code: ' ko' , name: ' Korean' , nativeName: ' 한국어' },
115+ { code: ' en' , name: ' English' , nativeName: ' English' },
42116 ],
43117 namespaces: [' common' , ' auth' ],
44118 loadTranslations : async (language , namespace ) => {
@@ -56,11 +130,7 @@ const i18nConfig = createI18nConfig({
56130 userFriendlyMessages: true
57131 }
58132});
59- ```
60133
61- ### 2. Provider Setup
62-
63- ``` tsx
64134function App() {
65135 return (
66136 <I18nProvider config = { i18nConfig } >
@@ -70,59 +140,96 @@ function App() {
70140}
71141```
72142
73- ### 3. Translation Usage
74-
75- ``` tsx
76- function MyComponent() {
77- const { t, tWithParams } = useTranslation ();
78-
79- return (
80- <div >
81- <h1 >{ t (' common.welcome' )} </h1 >
82- <p >{ tWithParams (' common.greeting' , { name: ' John' })} </p >
83- </div >
84- );
85- }
86- ```
87-
88143## Translation File Structure
89144
90145``` text
91146translations/
92- ├── en /
147+ ├── ko /
93148│ ├── common.json
94149│ └── auth.json
95- └── ko /
150+ └── en /
96151 ├── common.json
97152 └── auth.json
98153```
99154
100155### Translation File Examples
101156
102157``` json
103- // translations/en /common.json
158+ // translations/ko /common.json
104159{
105- "welcome" : " Welcome " ,
106- "greeting" : " Hello , {{name}}!" ,
160+ "welcome" : " 환영합니다 " ,
161+ "greeting" : " 안녕하세요 , {{name}}님 !" ,
107162 "buttons" : {
108- "save" : " Save " ,
109- "cancel" : " Cancel "
163+ "save" : " 저장 " ,
164+ "cancel" : " 취소 "
110165 }
111166}
112167```
113168
114169``` json
115- // translations/ko /common.json
170+ // translations/en /common.json
116171{
117- "welcome" : " 환영합니다 " ,
118- "greeting" : " 안녕하세요 , {{name}}님 !" ,
172+ "welcome" : " Welcome " ,
173+ "greeting" : " Hello , {{name}}!" ,
119174 "buttons" : {
120- "save" : " 저장 " ,
121- "cancel" : " 취소 "
175+ "save" : " Save " ,
176+ "cancel" : " Cancel "
122177 }
123178}
124179```
125180
181+ ## withDefaultConfig() Options
182+
183+ ``` tsx
184+ export const I18nProvider = withDefaultConfig ({
185+ // Default language (default: 'ko')
186+ defaultLanguage: ' en' ,
187+
188+ // Fallback language (default: 'en')
189+ fallbackLanguage: ' ko' ,
190+
191+ // Namespaces (default: ['common'])
192+ namespaces: [' common' , ' auth' , ' dashboard' ],
193+
194+ // Debug mode (default: NODE_ENV === 'development')
195+ debug: true ,
196+
197+ // Auto language sync events (default: true)
198+ // Automatically registers event listeners: huaI18nLanguageChange, i18nLanguageChanged
199+ // Automatically detects browser language changes or external language switching events
200+ autoLanguageSync: true ,
201+ });
202+ ```
203+
204+ ### autoLanguageSync Option Details
205+
206+ The ` autoLanguageSync ` option automatically detects and handles language switching events:
207+
208+ ``` tsx
209+ // Events that are automatically detected
210+ window .addEventListener (' huaI18nLanguageChange' , (event ) => {
211+ // SDK internal language change event
212+ const newLanguage = event .detail ;
213+ });
214+
215+ window .addEventListener (' i18nLanguageChanged' , (event ) => {
216+ // General language change event
217+ const newLanguage = event .detail ;
218+ });
219+ ```
220+
221+ ** Usage Example:**
222+
223+ ``` tsx
224+ // When changing language from other components
225+ const changeLanguage = (language ) => {
226+ // Event dispatch → withDefaultConfig() automatically detects
227+ window .dispatchEvent (new CustomEvent (' i18nLanguageChanged' , {
228+ detail: language
229+ }));
230+ };
231+ ```
232+
126233## Advanced Features
127234
128235### Language Switching
@@ -155,9 +262,9 @@ import { ssrTranslate } from 'hua-i18n-sdk';
155262
156263export default function ServerComponent() {
157264 const title = ssrTranslate ({
158- translations: translations .en .common (),
265+ translations: translations .ko .common (),
159266 key: ' common.welcome' ,
160- language: ' en ' ,
267+ language: ' ko ' ,
161268 });
162269
163270 return <h1 >{ title } </h1 >;
@@ -187,11 +294,11 @@ t('common.invalid'); // ❌ Type error
187294
188295## Error Handling (v1.1.0)
189296
190- ### Automatic Retry and Recovery
297+ ### Auto-retry and Recovery
191298
192299``` tsx
193300const config = {
194- // ... basic configuration
301+ // ... basic config
195302 errorHandling: {
196303 recoveryStrategy: {
197304 maxRetries: 3 ,
@@ -277,6 +384,7 @@ const config: I18nConfig = {
277384- [ SDK Reference] ( ./docs/SDK_REFERENCE.md ) - Complete API documentation
278385- [ Changelog] ( ./docs/CHANGELOG.md ) - Version changes
279386- [ Environment Guides] ( ./docs/ENVIRONMENT_GUIDES.md ) - Various environment setups
387+ - [ Environment Examples] ( ./docs/ENVIRONMENT_EXAMPLES.md ) - Environment-specific setup examples
280388- [ Contributing Guide] ( ./CONTRIBUTING.md ) - How to contribute to the project
281389
282390## Testing
@@ -291,7 +399,6 @@ npm run test:coverage
291399
292400``` bash
293401npm run build
294- npm run build:types
295402```
296403
297404## Contributing
0 commit comments