sheet-i18n 1.9.7 → 1.10.0-canary.0

package/README.md

@@ -31,6 +31,10 @@ npm install @sheet-i18n/cli -D
 
 ### `@sheet-i18n/react`
 
+# @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.
@@ -42,11 +46,12 @@ This package provides tools to handle translations in React applications using c
 - **`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.
+- **`ruleFactory`**: _Rule Factory Function_ for creating custom translation rules with conditional logic.
 
 ## 🚀 Getting Started(Manually)
 
 > ⚡ **Strongly recommended to use the init CLI for setup**
-> 👉 [Please follow the Init CLI section](#initial-setup-anchor)
+> 👉 [Please follow the Init CLI](https://www.npmjs.com/package/@sheet-i18n/cli)
 >
 > If you don't want to use the CLI, you can follow the `Manual Setup` below.
 
@@ -77,8 +82,8 @@ Prepare locale JSON files:
 this store will be used as a core translations module.
 
 ```tsx
-import ko from './ko.json';
 import en from './en.json';
+import ko from './ko.json';
 
 import { I18nStore } from '@sheet-i18n/react';
 
@@ -166,6 +171,7 @@ The `I18nStore` manages translation states, ensuring consistency across locales.
 | 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.
@@ -174,7 +180,7 @@ The `I18nStore` manages translation states, ensuring consistency across locales.
 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 = () => {
@@ -234,9 +240,6 @@ For projects with many locale datasets, it's often preferable to load translatio
 #### Example:
 
 ```tsx
-import ko from './locales/ko.json';
-import en from './locales/en.json';
-
 export const i18nStore = new I18nStore({
   supportedLocales: ['ko', 'en'],
   defaultLocale: 'ko',
@@ -263,6 +266,8 @@ Generates React context, including the `IntlProvider` and `useTranslation`.
 #### Parameters:
 
 - **`i18nStore`**: Instance of `I18nStore`.
+- **`plugins`** (optional): Plugin configuration object.
+  - **`rules`** (optional): Custom rules object for conditional translations. See [Plugins](#-plugins) section for details.
 
 > ⚠️ Caveats:
 >
@@ -334,31 +339,93 @@ A function to access translations in the environment where cannot use react cont
 
 ### `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.
+The `t` function is used to retrieve translation strings based on keys and optionally interpolate variables. It provides flexibility to include dynamic values, such as plain strings or React components, for enhanced localization capabilities.
 
-#### Parameters:
+#### **Overview: `t()`, `t.rule()`, and `t.dynamic()`**
+
+| Method                              | Use Case                                   | Key Type                             | When to Use                                                         |
+| ----------------------------------- | ------------------------------------------ | ------------------------------------ | ------------------------------------------------------------------- |
+| **`t(key, values?)`**               | Standard translation with explicit keys    | Static (known at build time)         | When you know the translation key beforehand                        |
+| **`t.rule(ruleKey, values?)`**      | Conditional translation using custom rules | Determined by rule function          | When you need conditional logic (pluralization, gender-based, etc.) |
+| **`t.dynamic(id, values?, opts?)`** | Translation with runtime keys              | Dynamic (from API, user input, etc.) | When the translation key comes from runtime data                    |
+
+#### **`t()` - Standard Translation**
+
+Retrieve translations for explicit keys that are known at build time.
 
-- key (string): The translation key to retrieve the localized string.
+##### Parameters:
+
+- **`key`** (string): The translation key to retrieve the localized string.
+- **`values`** (object, optional): An object containing key-value pairs to interpolate into the translation string.
+
+##### Examples:
 
 ```tsx
-const translatedMessage = t('login'); // login is key
+const { t } = useTranslation('header');
+
+// Simple translation
+const loginText = t('login'); // "Login" or "로그인"
+
+// Translation with interpolation
+const welcomeMessage = t('{username} shown', { username: 'John Doe' });
+// Result: "John Doe shown"
+
+// Interpolation with React components
+const message = t('{username} shown', { username: <Username /> });
 ```
 
-- values (object, optional): An object containing key-value pairs to interpolate into the translation string.
+💡 **Note**: The values object can contain any type of data, including React components.
+
+#### **`t.rule()` - Conditional Translation with Custom Rules**
+
+Use custom rules for conditional translations based on dynamic values. This method is available when custom rules are registered via the `createI18nContext` plugins option.
+
+##### Parameters:
+
+- **`ruleKey`** (string): The key of the registered custom rule.
+- **`values`** (object, optional): An object containing values to be passed to the rule function and used for interpolation.
+
+##### Examples:
 
 ```tsx
-// John Doe shown
-const translatedMessage = t('{username} shown', { username: 'John Doe' });
+// Assuming custom rules are registered
+const { t } = useTranslation('landing');
+
+// Call rule with values
+const message = t.rule('plural', { age: 21 });
+// The rule function determines which translation key to use based on age
 ```
 
-💡 Note: The values object can contain any type of data, including React components.
+💡 **Note**: `t.rule()` works exactly like `t()` in terms of interpolation. If the translation key returned by the rule function contains `{slot}` placeholders, they will be automatically replaced using the values object passed to `t.rule()`.
+
+For more details, see the [Plugins](#-plugins) section.
+
+#### **`t.dynamic()` - Runtime Key Translation**
+
+Resolve translation keys that are not known at build time (e.g., values coming from API responses, user input, or other runtime sources).
+
+##### Parameters:
+
+- **`id`** (string): A runtime string to match against the current locale's translation keys.
+- **`values`** (object, optional): Interpolation values, identical to `t()`.
+- **`opts`** (object, optional): Formatter options.
+
+##### Examples:
 
 ```tsx
-// <Username /> shown
-const translatedMessage = t('{username} shown', { username: <Username /> });
+const { t } = useTranslation('header');
+const { data } = useQuery(...queryOptions);
+
+// Runtime key from API response
+const deviceName = data?.device?.name; // e.g., "smartphone"
+
+// Will translate the runtime key if it exists in the current locale
+const label = t.dynamic(deviceName);
+// If "smartphone" exists in locale JSON, returns translated value
+// Otherwise, returns "smartphone" as fallback
 ```
 
-<br/>
+💡 **Tip**: Ensure your locale JSON contains possible runtime keys; otherwise `t.dynamic` will fall back to the provided id string.
 
 ## 📄 Best Practices of Translation utilities
 
@@ -414,11 +481,6 @@ return <div>{t.dynamic(deviceName)}</div>;
 
 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 call expression of `t` function is evaluated at runtime**
@@ -453,32 +515,46 @@ export default function App() {
 
 - 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.
+- In this case, use **`getTranslation`** and **`watch`** CLI for easy translation workflow.
 
 #### **Example**
 
 ```tsx
 // module.ts
-// The "t" result in the array will be resolved asynchronously
+// the "t" function from "getTranslation" is used as the "marker" of "watch" CLI
 import { getTranslation } from './i18nContext';
 
 const { t } = getTranslation('header');
 
 export const STATUS_CATEGORY = [
-  t.promise('Total Energy Usage'),
-  t.promise('Total Waste Usage'),
+  t('Total Energy Usage'), // Marked
+  t('Total Waste Usage'), // Marked
 ];
 
+// Pre-requisite: install @sheet-i18n/cli and run `npx sheet-i18n watch`
+// You can register your translation data with ease
+Detected Translations:
+
+📄 [Sheet Title]: header
+ - Total Energy Usage
+ - Total Waste Usage
+
+# You can proceed using the shortcuts below:
+ - Press <Shift + R> to register the detected changes. // <-- you can register your translation data
+ - Press <Ctrl + C> to cancel the watch command.
+
 // App.tsx
-// So, t.promise ensure the current client-side locale data
-// is fully initialized before the translations are resolved
+// After update of translation data, t.dynamic will resolve the translations
+// If you want to translate the text with type safety, use "t" function which works like t.dynamic after register and import your translation data.
 import { STATUS_CATEGORY } from './module.ts';
 
 export default function App() {
+  const { t } = useTranslation('header');
+
   return (
     <div>
       {STATUS_CATEGORY.map((item, index) => {
-        return <div key={index}>{item}</div>;
+        return <div key={index}>{t.dynamic(item)}</div>;
       })}
     </div>
   );
@@ -610,6 +686,117 @@ const customStorageManager = getLocaleStorageManager(
 );
 ```
 
+#### **Storage Options**
+
+- **LocalStorage (Default)**: Persists across browser sessions and device restarts
+- **SessionStorage**: Persists only for the current browser session
+- **Custom Storage**: Implement your own persistence strategy (e.g., server-side storage, encrypted storage)
+- **Memory Storage**: No persistence (for testing or temporary use cases)
+
+## 🔌 Plugins
+
+sheet-i18n provides an extensible plugin system that allows you to customize translation logic and easily implement conditional translations or complex translation rules.
+
+### 🎯 Custom Rules Plugin
+
+**Custom Rules** is a plugin that enables dynamic selection of different translation keys based on conditions. This allows you to implement various scenarios such as pluralization, gender-based translations, age-based message changes, and more.
+
+#### **Key Features**
+
+- ✅ **Conditional Translation**: Automatically select different translation keys based on values
+- ✅ **Interpolation Support**: Same `{slot}` replacement functionality as the `t` function
+- ✅ **Extensible**: Combine multiple rules to implement complex logic
+
+##### **Key Points**
+
+```tsx
+import { ruleFactory } from '@sheet-i18n/react';
+import { i18nStore } from './i18nStore';
+
+// Step 1: Create factory service
+// ruleFactory takes your i18nStore and returns an object with createRule method
+const { createRule } = ruleFactory(i18nStore);
+
+// Step 2: Use createRule to define custom rules
+// `createRule` can take a rule function and support the current localeSet data use registered in the localeSet of `i18nStore`
+// In the body of the rule function, you can defined the translation logic as you want
+
+// 💡 Note: Highly recommended to return the translation key from the localeSet
+// When you use `t.rule()` from the component, the translation key will be resolved and the translated text will be returned
+// If you return the normal string, that string will be used as the translation key
+// and If no matched translation key is found, the string will be used rendered
+const myRule = createRule<{ count: number }>((values, localeSet) => {
+  if (values.count > 10) {
+    return localeSet.sheetTitle['many_items'];
+  }
+  return localeSet.sheetTitle['few_items'];
+});
+```
+
+##### **Complete Flow Example**
+
+```tsx
+// Translation data example from your sheet
+// en.json
+{
+  ...
+  "userSheet": {
+    "adult_message": "You are an adult. Your age is {age}",
+    "youth_message": "You are a youth. Your age is {age}"
+  }
+}
+
+// 1. Initialize i18nStore
+const i18nStore = new I18nStore({
+  /* ... */
+});
+
+// 2. Create factory service (binds createRule to i18nStore)
+const { createRule } = ruleFactory(i18nStore);
+
+// 3. Define custom rules using createRule
+export const customRules = {
+  ageRule: createRule<{ age: number }>((values, localeSet) => {
+    if (values.age > 20) {
+      return localeSet.userSheet['adult_message'];
+    }
+    return localeSet.userSheet['youth_message'];
+  }),
+};
+
+// 4. Register rules in context
+const { useTranslation } = createI18nContext(i18nStore, { rules: customRules });
+
+// 5. Use in components
+const { t } = useTranslation('userSheet');
+const translatedText = t.rule('ageRule', { age: 25 }); // 'You are an adult. Your age is 25'
+```
+
+💡 **Core Concept**:
+
+- `localeSet` contains the complete translation data for the current locale, accessible via `localeSet.landing['key_name']`.
+- The returned translation key is processed the same way as the `t()` function to convert it to the final translated value.
+- If the returned translation key contains `{slot}` placeholders, they will be automatically replaced using the `values` object passed to `t.rule()`.
+
+💡 **Important**: If you want to use auto-replaced interpolation, you should use the same sheetTitle in the `useTranslation` hook and the localeSet in the `t.rule` function
+
+```ts
+// Example
+// you return the translation key from 'userSheet' in the localeSet
+const customRules = {
+  ageRule: createRule<{ age: number }>((values, localeSet) => {
+    if (values.age > 20) {
+      return localeSet.userSheet['adult_message'];
+    }
+    return localeSet.userSheet['youth_message'];
+  }),
+};
+
+// you should use the 't.rule' function from the same sheetTitle for the argument of `useTranslation`
+const { t } = useTranslation('userSheet');
+const translatedText = t.rule('ageRule', { age: 25 }); // 'You are an adult. Your age is 25'
+```
+
 </details>
 
 ---
@@ -620,6 +807,8 @@ const customStorageManager = getLocaleStorageManager(
 
 ### `@sheet-i18n/cli`
 
+[![npm package](https://img.shields.io/npm/v/@sheet-i18n/cli)](https://npmjs.com/package/@sheet-i18n/cli)
+
 A CLI tool for efficient translation management using Google Sheets, with a focus on developer experience (DX).
 
 ## Features
@@ -991,6 +1180,8 @@ The configuration of export command is based on **`sheet.config.ts`** on your ro
 
 ### `sheet-i18n/importer`
 
+[![npm package](https://img.shields.io/npm/v/@sheet-i18n/importer)](https://npmjs.com/package/@sheet-i18n/importer)
+
 The **server-side importer** subpackage allows you to interact with Google Sheets and export translations directly into your project. This is primarily used in server-side environments, such as Next.js API routes or other backend frameworks, where you want to fetch and store translations from a Google Spreadsheet to be served to clients or used within your server application.
 
 ```jsx

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sheet-i18n",
   "description": "All-in-one i18n toolchain: seamlessly integrate Google Sheets, CLI, and react-i18n for easy translation workflows.",
-  "version": "1.9.7",
+  "version": "1.10.0-canary.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/chltjdrhd777/sheet-i18n"
@@ -50,9 +50,9 @@
   "license": "ISC",
   "homepage": "https://github.com/chltjdrhd777/sheet-i18n",
   "dependencies": {
-    "@sheet-i18n/importer": "1.9.5",
+    "@sheet-i18n/react": "1.6.0-canary.0",
     "@sheet-i18n/typescript": "0.2.2",
-    "@sheet-i18n/react": "1.5.3"
+    "@sheet-i18n/importer": "1.9.5"
   },
   "devDependencies": {
     "tsup": "^6.0.0",