@sheet-i18n/react 1.0.4 → 1.0.6

package/README.md

@@ -1,5 +1,3 @@
-# @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.
@@ -227,33 +225,12 @@ const translatedMessage = t('login');
 
 ### `getTranslation`
 
-A hook to access translations in static modules.
+A function to access translations in the environment where cannot use react context and hooks.
 
 #### Parameters:
 
 - **`sheetTitle`**: The sheet title of the translation group.
 
-#### Example:
-
-```tsx
-// data.ts
-import { getTranslation } from './i18nContext';
-
-const { t } = getTranslation('header');
-
-export const STATUS_CATEGORY = [
-  t('Total Energy Usage'),
-  t('Total Waste Usage'),
-];
-
-// App.tsx
-import { STATUS_CATEGORY } from './data';
-
-export default function App() {
-  return STATUS_CATEGORY.map((item) => <div>{item}</div>);
-}
-```
-
 ### `t Function`
 
 The t function is used to retrieve a translation string based on a key and optionally interpolate variables. It provides flexibility to include dynamic values, such as plain strings or React components, for enhanced localization capabilities.
@@ -290,7 +267,7 @@ A robust and flexible translation library designed for efficient handling of tra
 
 - **Client-Side Translation (Explicit Strings)**: Translate explicit string keys directly in your components.
 - **Client-Side Translation (Dynamic Strings)**: Dynamically match translations from JSON for unknown variables.
-- **Static Module Translation**: Use translations in static modules for configuration constants.
+- **Module Translation**: Use translations in the place where the react context or hooks cannot be used.
 
 ### Usage
 
@@ -332,30 +309,78 @@ const deviceName = data?.device?.name;
 return <div>{t.dynamic(deviceName)}</div>;
 ```
 
-#### 3. **Static Module Translation**
+#### 3. **Module Translation**
+
+The `getTranslation` function allows you to use translations outside of React components, such as in static configuration files, constants, or utility modules.
+
+It provide two possible supports
+
+1. **`t` (Synchronous Translation)** – Use when translation values are available **at runtime**.
+2. **`t.promise` (Asynchronous Translation)** – Use when the module’s evaluation order is uncertain.
+
+#### **✅ Usage Scenarios**
+
+#### **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.
+
+##### **Example**
+
+```tsx
+// module.ts
+import { getTranslation } from './i18nContext';
+
+const { t } = getTranslation('header');
+
+export function getStatusCategory {
+  return [t('Total Energy Usage'), t('Total Waste Usage')];
+};
+
+// App.tsx
+// the "t" call expression is evaluated at function call timing
+import { getStatusCategory } from './module';
+
+export default function App() {
+  return getStatusCategory().map((item) => <div>{item}</div>);
+}
+```
+
+**Result:** The translation is resolved **immediately** during runtime.
 
-Use `getTranslation` to initialize translations for static configurations, constants, or data that needs to be translated.
+#### **⚠️ Scenario 2: Context where the translation value is evaluated immediately**
 
-The **"t"** function from `getTranslation` returns a **Promise** that resolves to the translated string.
+- 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.
+- In this case, use **`t.promise`** to ensure the translation resolves asynchronously.
 
-> 💡 Note <br/>
-> The **`t`** function returned by **`getTranslation`** resolves its Promise in the background. For display purposes, you don't need to wait for the Promise to resolve, allowing you to use it without async/await.<br/> However, if you need to work with the fulfilled translated value during runtime, you have use async/await to retrieve it.
+#### **Example**
 
 ```tsx
-// data.ts
+// module.ts
+// The "t" result in the array will be resolved asynchronously
 import { getTranslation } from './i18nContext';
+
 const { t } = getTranslation('header');
 
 export const STATUS_CATEGORY = [
-  t('Total Energy Usage'),
-  t('Total Waste Usage'),
+  t.promise('Total Energy Usage'),
+  t.promise('Total Waste Usage'),
 ];
 
 // App.tsx
-import { STATUS_CATEGORY } from './data';
+// So, t.promise ensure the current client-side locale data
+// is fully initialized before the translations are resolved
+import { STATUS_CATEGORY } from './module.ts';
 
 export default function App() {
-  return STATUS_CATEGORY.map((item) => <div>{item}</div>);
+  return (
+    <div>
+      {STATUS_CATEGORY.map((item, index) => {
+        return <div key={index}>{item}</div>;
+      })}
+    </div>
+  );
 }
 ```
 
@@ -383,5 +408,3 @@ This project is licensed under the ISC License.
 **devAnderson**  
 [GitHub](https://github.com/chltjdrhd777)  
 [chltjdrhd777@gmail.com](mailto:chltjdrhd777@gmail.com)
-
-</details>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sheet-i18n/react",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "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.3.5"
+    "@sheet-i18n/typescript-config": "1.3.6"
   },
   "dependencies": {
-    "@sheet-i18n/react-core": "1.0.3",
-    "@sheet-i18n/react-client": "1.0.4"
+    "@sheet-i18n/react-client": "1.0.6",
+    "@sheet-i18n/react-core": "1.0.4"
   },
   "scripts": {
     "build": "tsup",