@sheet-i18n/react 1.2.1 → 1.3.0

package/README.md

@@ -1,27 +1,20 @@
-# @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`**: _Core Store Creation Class_ for managing translation data.
+- **`I18nStore`**: _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(Manually)
+## 🚀 Getting Started
 
-> ⚡ **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.
+### Basic Usage
 
-### step 1. Define Translation Data
+#### 1. Define Translation Data
 
 Prepare locale JSON files:
 
@@ -43,7 +36,7 @@ Prepare locale JSON files:
 }
 ```
 
-### step 2. Initialize i18nStore
+#### 2. Initialize i18nStore
 
 this store will be used as a core translations module.
 
@@ -67,13 +60,11 @@ export const i18nStore = new I18nStore({
   // dynamicLoaders: {
   //   ko: () => import('./ko.json'),
   //   en: () => import('./en.json'),
-  //   jp: () => import('./jp.json'),
-  //   cn: () => import('./cn.json'),
   // },
 });
 ```
 
-### step 3. Create i18n Context
+#### 3. Create i18n Context
 
 ```tsx
 import { i18nStore } from './file-path-of-i18nStore-initiated';
@@ -83,24 +74,22 @@ export const { IntlProvider, useTranslation, getTranslation } =
   createI18nContext(i18nStore);
 ```
 
-### step 4. Mount Intl Context Provider in your App
+#### 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 currentLocale={locale}>
+    <IntlProvider>
       <YourComponent />
     </IntlProvider>
   );
 };
 ```
 
-### step 5. Use Translations
+#### 5. Use Translations
 
 ```tsx
 import React from 'react';
@@ -124,29 +113,27 @@ const YourComponent = () => {
 
 ### `I18nStore(core)`
 
-The `I18nStore` manages translation states, ensuring consistency across locales.
+The `I18nStore` manages type-safe translation states, ensuring consistency across locales.
 
 #### Parameters:
 
-### 🧠 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`).                                                     |
-|                    |
+- **`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.
 
 > 💡 **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 = () => {
@@ -161,47 +148,12 @@ supportedLocales in i18nStore`
 >   );
 > };
 > ```
->
+
 > ⚠️ Caveats:
 >
 > 1. `supportedLocales` must be an array of locale strings.
 > 2. `defaultLocale` must exist in `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.
+> 3. `localeSet` must be an object with keys matching `supportedLocales`.
 
 #### Example:
 
@@ -219,8 +171,6 @@ export const i18nStore = new I18nStore({
   // dynamicLoaders: {
   //   ko: () => import('./ko.json'),
   //   en: () => import('./en.json'),
-  //   jp: () => import('./jp.json'),
-  //   cn: () => import('./cn.json'),
   // },
 });
 ```
@@ -254,7 +204,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 user-preferred language is not unsupported in the `supportedLocales`.
+  - The fallback is the default locale in **i18nStore** if the detected language is unsupported.
 
 - **`children`**: React children.
 
@@ -390,7 +340,7 @@ It provide two possible supports
 
 #### **✅ Usage Scenarios**
 
-#### **[Scenario 1]: Context where the call expression of `t` function is evaluated at runtime**
+#### **Scenario 1: Context where the translation value is evaluated at runtime**
 
 - For the common example, **t** call expression in a **function module**
 - This behaves the same as `useTranslation`'s `t` function.
@@ -418,7 +368,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.
@@ -454,10 +404,27 @@ export default function App() {
 }
 ```
 
-## License 📜
+## 🛠 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
 
-This project is licensed under the ISC License. See the LICENSE file for details.
+This project is licensed under the ISC License.
 
-## Author ✍️
+## 👤 Author
 
-Created by [devAnderson](https://github.com/chltjdrhd777).
+**devAnderson**  
+[GitHub](https://github.com/chltjdrhd777)  
+[chltjdrhd777@gmail.com](mailto:chltjdrhd777@gmail.com)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sheet-i18n/react",
-  "version": "1.2.1",
+  "version": "1.3.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.5.1"
+    "@sheet-i18n/typescript-config": "1.6.0"
   },
   "dependencies": {
-    "@sheet-i18n/react-core": "1.2.1",
-    "@sheet-i18n/react-client": "1.2.1"
+    "@sheet-i18n/react-core": "1.3.0",
+    "@sheet-i18n/react-client": "1.3.0"
   },
   "scripts": {
     "build": "tsup",