sheet-i18n 1.3.9 → 1.3.11

package/README.md

@@ -30,9 +30,9 @@ The `sheet-i18n` ecosystem is divided into three main packages:
 - `sheet-i18n/react`
 - `@sheet-i18n/cli`
 
----
+<br/>
 
-<details open>
+<details>
 <summary>🌍 Server Export Function - sheet-i18n/exporter</summary>
 
 #### `sheet-i18n/exporter`
@@ -152,9 +152,9 @@ The exported translations will be saved in a format that is easy to use for loca
 <details>
 <summary>⚛️ Frontend Translation Provider - sheet-i18n/react</summary>
 
-#### `sheet-i18n/react`
+### `@sheet-i18n/react`
 
-The **client-side i18n library** subpackage.
+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.
 
@@ -163,7 +163,8 @@ This package provides tools to handle translations in React applications using c
 - **`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`**: _Translation Hook_ for easy access to translation messages.
+- **`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
 
@@ -380,33 +381,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.
@@ -443,7 +423,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
 
@@ -485,30 +465,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>
+  );
 }
 ```
 
@@ -700,6 +728,9 @@ Example `sheet.config.json`:
 
 ```json
 {
+  "watchEntry": "src",
+  "detectExtensions": ["tsx", "ts", "jsx", "js"],
+
   "googleSheetConfig": {
     "credentials": {
       "sheetId": "YOUR_GOOGLE_SHEET_ID",
@@ -714,9 +745,9 @@ Example `sheet.config.json`:
 }
 ```
 
-#### 1. Watch command configuration
+#### 1. File change monitoring configuration
 
-- `watchDirectory` (optional): Path of the directory to monitor during `watch` command based on the current working directory (default: `src`)
+- `watchEntry` (optional): Entry path to detect file changes relative to current working directory (default: `src`)
 - `detectExtensions` (optional): File extensions to monitor (default: `jsx`, `js`, `tsx`, `ts`).
 
 #### 2. Register command configuration
@@ -745,7 +776,7 @@ Sets up the `sheet.config.json` file in your project. This configuration file is
 ### 👀 watch
 
 ```shell
-npx sheet-i18n watch [options]
+npx sheet-i18n watch
 ```
 
 Monitors files or directories for changes and logs relevant updates.
@@ -787,16 +818,6 @@ The _watch result_ is
  }
 ```
 
-#### Options:
-
-- `-d, --directory <directory>`: Specify the directory to watch.
-
-Example:
-
-```shell
-npx sheet-i18n watch --directory src
-```
-
 </br>
 
 ### 📤 register
@@ -817,10 +838,6 @@ Registers translation data to Google Sheets.
 
 #### Options:
 
-- `-d, --directory <directory>`  
-  Specify the directory to scan for translation data, relative to the current working directory.  
-  **Default**: `src`
-
 - `-s, --scope <scope>`  
   Define the scope of the registration process:
   - **`diff`**: Only scans translation keys that have been modified in the Git history (based on `git diff`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sheet-i18n",
-  "version": "1.3.9",
+  "version": "1.3.11",
   "repository": {
     "type": "git",
     "url": "https://github.com/chltjdrhd777/sheet-i18n"
@@ -36,13 +36,13 @@
   },
   "license": "ISC",
   "dependencies": {
-    "@sheet-i18n/exporter": "1.3.5",
-    "@sheet-i18n/react": "1.0.4"
+    "@sheet-i18n/exporter": "1.3.7",
+    "@sheet-i18n/react": "1.0.6"
   },
   "devDependencies": {
     "tsup": "^6.0.0",
     "typescript": "^5.0.0",
-    "@sheet-i18n/typescript-config": "1.3.5"
+    "@sheet-i18n/typescript-config": "1.3.6"
   },
   "scripts": {
     "build": "tsup",