@sheet-i18n/react 1.3.0 → 1.4.0

package/README.md

@@ -1,20 +1,27 @@
+# @sheet-i18n/react ✨
+
+[![npm package](https://img.shields.io/npm/v/@sheet-i18n/react)](https://npmjs.com/package/@sheet-i18n/react)
+
 The **client-side i18n library** subpackage of sheet-i18n.
 
 This package provides tools to handle translations in React applications using context and hooks. It simplifies internationalization workflows by offering functions and components to manage, access, and use locale-specific translation data.
 
 ## ✨ Package Introduction
 
-- **`I18nStore`**: _Store Creation Class_ for managing translation data.
+- **`I18nStore`**: _Core Store Creation Class_ for managing translation data.
 - **`createI18nContext`**: _React Context_ to generate providers and hooks for translation.
 - **`IntlProvider`**: _React Translation Provider_ for managing current locale.
 - **`useTranslation`**: _Client Side Translation Hook_ for easy access to translation messages on the client side.
 - **`getTranslation`**: _Static Translation Function_ for easy access to translation messages on Static module files.
 
-## 🚀 Getting Started
+## 🚀 Getting Started(Manually)
 
-### Basic Usage
+> ⚡ **Strongly recommended to use the init CLI for setup**
+> 👉 [Please follow the Init CLI section](#initial-setup-anchor)
+>
+> If you don't want to use the CLI, you can follow the `Manual Setup` below.
 
-#### 1. Define Translation Data
+### step 1. Define Translation Data
 
 Prepare locale JSON files:
 
@@ -36,7 +43,7 @@ Prepare locale JSON files:
 }
 ```
 
-#### 2. Initialize i18nStore
+### step 2. Initialize i18nStore
 
 this store will be used as a core translations module.
 
@@ -60,11 +67,13 @@ export const i18nStore = new I18nStore({
   // dynamicLoaders: {
   //   ko: () => import('./ko.json'),
   //   en: () => import('./en.json'),
+  //   jp: () => import('./jp.json'),
+  //   cn: () => import('./cn.json'),
   // },
 });
 ```
 
-#### 3. Create i18n Context
+### step 3. Create i18n Context
 
 ```tsx
 import { i18nStore } from './file-path-of-i18nStore-initiated';
@@ -74,22 +83,24 @@ export const { IntlProvider, useTranslation, getTranslation } =
   createI18nContext(i18nStore);
 ```
 
-#### 4. Mount Intl Context Provider in your App
+### step 4. Mount Intl Context Provider in your App
 
 ```tsx
 import React from 'react';
 import { IntlProvider } from './i18nContext';
 
 const App = () => {
+  const [locale, setLocale] = useState('en');
+
   return (
-    <IntlProvider>
+    <IntlProvider currentLocale={locale}>
       <YourComponent />
     </IntlProvider>
   );
 };
 ```
 
-#### 5. Use Translations
+### step 5. Use Translations
 
 ```tsx
 import React from 'react';
@@ -113,27 +124,29 @@ const YourComponent = () => {
 
 ### `I18nStore(core)`
 
-The `I18nStore` manages type-safe translation states, ensuring consistency across locales.
+The `I18nStore` manages translation states, ensuring consistency across locales.
 
 #### Parameters:
 
-- **`supportedLocales`**: Array of supported locale strings.
-  <br/>
-  <br/>
-- **`defaultLocale`**: The default locale, included in `supportedLocales`.
-  <br/>
-  <br/>
-- **`localeSet(optional. choice 1)`**: An object where keys match `supportedLocales`, and values are translation sets. If you want to use this option, you need to provide all static locale data according to the `supportedLocales`.
-  <br/>
-  <br/>
-- **`dynamicLoaders(optional. choice 2)`**: An object where keys match `supportedLocales`, and values are dynamic translation loader functions.
-  <br/>
-  <br/>
-- **`typeSafe(optional, default = false)`**: An optional boolean indicating whether to use type-safe translations.
+### 🧠 I18nStore Configuration Options
+
+| Option             | Type                               | Required | Description                                                                                                           |
+| ------------------ | ---------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
+| `supportedLocales` | string[]                           | ✅       | List of supported locale codes.                                                                                       |
+| `defaultLocale`    | string                             | ✅       | Default locale to use when no match is found. Must be included in `supportedLocales`.                                 |
+| localeSet          | Record<string, object>             |          | _(Static Loading Option)_ Preload all translation data for each locale in memory. Keys must match `supportedLocales`. |
+| dynamicLoaders     | Record<string, () => Promise<any>> |          | _(Recommended for large locale sets)_ Dynamically load translation data on demand, reducing initial bundle size.      |
+| typeSafe           | boolean                            |          | Enable strict key checking and autocompletion (default: `false`).                                                     |
+|                    |
 
 > 💡 **typeSafe?** <br/>
 > I18nStore doesn't enforce adherence to your locale JSON definitions by default. This means that you can add translation data even if it isn’t pre-defined in your locale JSON files. However, if you prefer to enforce strict type-safety, you can manually enable the typeSafe option which allows you to notice the auto-completed list in translation data.
 >
+> But to enable correct type checking, `the full localeSet must be defined according to the
+supportedLocales in i18nStore`
+>
+> As a result, type auto-completion relies on having the complete localeSet defined at initialization. This means that using dynamicLoaders to fetch locales conditionally at runtime can be limiting when strict type-safety is enabled.
+
 > ```tsx
 > // typeSafe: true
 > const YourComponent = () => {
@@ -148,12 +161,47 @@ The `I18nStore` manages type-safe translation states, ensuring consistency acros
 >   );
 > };
 > ```
-
+>
 > ⚠️ Caveats:
 >
 > 1. `supportedLocales` must be an array of locale strings.
 > 2. `defaultLocale` must exist in `supportedLocales`.
-> 3. `localeSet` must be an object with keys matching `supportedLocales`.
+
+### 🚀 Static vs Dynamic Loading
+
+You can configure how translations are loaded:
+
+- **Static (`localeSet`)**  
+  Load all translations at once. Ideal for small projects or limited locale sets.
+
+- **Dynamic (`dynamicLoaders`)** ✅ _Recommended_  
+  Load only the locale needed, reducing the bundle size dramatically.  
+  Useful when supporting many languages or large translation files.
+
+```ts
+export const i18nStore = new I18nStore({
+  supportedLocales: ['en', 'fr', 'ko'],
+  defaultLocale: 'en',
+  dynamicLoaders: {
+    en: () => import('./en.json'),
+    fr: () => import('./fr.json'),
+    ko: () => import('./ko.json'),
+  },
+});
+```
+
+💡 When both `localeSet` and `dynamicLoaders` are defined, sheet-i18n **automatically merges** both sources — static data loads immediately, while dynamic data supplements on-demand.
+
+---
+
+### 🎯 Why Dynamic Loaders?
+
+For projects with many locale datasets, it's often preferable to load translation data on demand rather than all at once. It is better using `dynamicLoaders` to enable this conditional loading strategy.
+
+- ✅ Reduces the initial JavaScript bundle size.
+- ✅ Keeps only required locales in memory.
+- ✅ Works well with code-splitting and SSR/CSR.
+- ✅ Enables **lazy-loading** for translations.
 
 #### Example:
 
@@ -171,6 +219,8 @@ export const i18nStore = new I18nStore({
   // dynamicLoaders: {
   //   ko: () => import('./ko.json'),
   //   en: () => import('./en.json'),
+  //   jp: () => import('./jp.json'),
+  //   cn: () => import('./cn.json'),
   // },
 });
 ```
@@ -204,7 +254,7 @@ A Context provider to provide translations to child components.
 
   - A key representing the current locale to use for translations.
   - If not provided, the user's preferred language is automatically detected based on the browser setting.
-  - The fallback is the default locale in **i18nStore** if the detected language is unsupported.
+  - The fallback is the default locale in **i18nStore** if the detected user-preferred language is not unsupported in the `supportedLocales`.
 
 - **`children`**: React children.
 
@@ -340,7 +390,7 @@ It provide two possible supports
 
 #### **✅ Usage Scenarios**
 
-#### **Scenario 1: Context where the translation value is evaluated at runtime**
+#### **[Scenario 1]: Context where the call expression of `t` function is evaluated at runtime**
 
 - For the common example, **t** call expression in a **function module**
 - This behaves the same as `useTranslation`'s `t` function.
@@ -368,7 +418,7 @@ export default function App() {
 
 **Result:** The translation is resolved **immediately** during runtime.
 
-#### **⚠️ Scenario 2: Context where the translation value is evaluated immediately**
+#### **[Scenario 2]: Context where the translation value is evaluated immediately**
 
 - If the module is **imported dynamically in a client-side component**, the evaluation order of `getTranslation` and `t` call expression may not be guaranteed.
 - Since JavaScript **evaluates modules at import time**, it may attempt to access translation values before `IntlProvider` has fully initialized the locale.
@@ -404,27 +454,10 @@ export default function App() {
 }
 ```
 
-## 🛠 Error Handling
-
-Custom error messages help identify misconfigurations:
-
-1. **Invalid Params**: Ensure `supportedLocales`, `defaultLocale`, and `localeSet` are correctly provided.
-2. **Missing Default Locale**: The `defaultLocale` must exist in `supportedLocales`.
-3. **Invalid LocaleSet**: Ensure the `localeSet` keys match `supportedLocales`.
-
-## 📜 Library Versions 🔢
-
-This package supports the following library versions:
-
-- **React**: `^19.0.0`
-- **React Intl**: `^7.0.4`
-
-## 📜 License
+## License 📜
 
-This project is licensed under the ISC License.
+This project is licensed under the ISC License. See the LICENSE file for details.
 
-## 👤 Author
+## Author ✍️
 
-**devAnderson**  
-[GitHub](https://github.com/chltjdrhd777)  
-[chltjdrhd777@gmail.com](mailto:chltjdrhd777@gmail.com)
+Created by [devAnderson](https://github.com/chltjdrhd777).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sheet-i18n/react",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "i18n client logic based on react",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -29,11 +29,11 @@
   "license": "ISC",
   "devDependencies": {
     "@swc/core": "^1.10.2",
-    "@sheet-i18n/typescript-config": "1.6.0"
+    "@sheet-i18n/typescript-config": "1.7.0"
   },
   "dependencies": {
-    "@sheet-i18n/react-core": "1.3.0",
-    "@sheet-i18n/react-client": "1.3.0"
+    "@sheet-i18n/react-core": "1.4.0",
+    "@sheet-i18n/react-client": "1.4.0"
   },
   "scripts": {
     "build": "tsup",