Skip to content

Commit 989b8ef

Browse files
committed
feat: Add beginner-friendly withDefaultConfig() and Easy Entry Point
- Add withDefaultConfig() for one-line setup - Add Easy Entry Point (hua-i18n-sdk/easy) for beginners - Add autoLanguageSync feature for automatic language change detection - Enhance documentation with beginner-friendly guides - Fix GitHub links and improve documentation structure - Add comprehensive tests for withDefaultConfig() - Update package version to 1.2.0 Breaking Changes: None Migration: Existing code works without changes
1 parent 441606e commit 989b8ef

File tree

14 files changed

+1667
-288
lines changed

14 files changed

+1667
-288
lines changed

CONTRIBUTING.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ Thank you for your interest in contributing to hua-i18n-sdk! This document provi
1717
2. Clone your fork:
1818

1919
```bash
20-
git clone https://github.com/YOUR_USERNAME/i18n-sdk.git
20+
git clone https://github.com/HUA-Labs/i18n-sdk.git
2121
cd i18n-sdk
2222
```
2323

README.en.md

Lines changed: 151 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,24 @@
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
34108
import { I18nProvider, useTranslation, createI18nConfig } from 'hua-i18n-sdk';
35109

36110
const 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
64134
function 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
91146
translations/
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

156263
export 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
193300
const 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
293401
npm run build
294-
npm run build:types
295402
```
296403

297404
## Contributing

0 commit comments

Comments
 (0)