sheet-i18n 1.6.0 → 1.7.1

package/README.md

@@ -1,156 +1,33 @@
-# sheet-i18n
+# sheet-i18n [![npm](https://img.shields.io/npm/v/sheet-i18n)](https://www.npmjs.com/package/sheet-i18n)
 
-**An all-in-one package for sheet-based translation**
+<img src="https://raw.githubusercontent.com/chltjdrhd777/image-hosting/refs/heads/main/sheet-i18n/banner_horizontal_sharp.png" />
+
+<br/>
 
-[![npm](https://img.shields.io/npm/v/sheet-i18n)](https://www.npmjs.com/package/sheet-i18n)  
 <a href="https://sheet-i18n.vercel.app/en" target="_blank">
 
 <!-- <img height="20px" src="https://img.shields.io/badge/📚-%20Docs-%23000000"/> -->
 </a>
 
-## Installation 🛠️
-
-You can install **sheet-i18n** via npm:
-
-```bash
-npm install sheet-i18n
-```
-
-## Usage 🚀
-
-### 📑 Main Package - `sheet-i18n`
-
 `sheet-i18n` is a **powerful and flexible library** designed to streamline the process of managing and utilizing translations stored in **Google Sheets** _(planned to support other spreadsheets soon)_.
 
 It serves as a bridge between your translation data and your application, offering an **end-to-end solution** for exporting, managing, and integrating translations into your projects.
 
 The `sheet-i18n` ecosystem is divided into three main packages:
 
-- `sheet-i18n/importer`
 - `sheet-i18n/react`
 - `@sheet-i18n/cli`
+- `sheet-i18n/importer`
 
-<br/>
-
-<details open>
-<summary>🌍 Server Export Function - sheet-i18n/importer</summary>
-
-#### `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
-import { googleSheetImporter } from 'sheet-i18n/importer';
-
-const importer = await googleSheetImporter({
-  credentials: {
-    sheetId: 'your-google-sheet-id',
-    clientEmail: 'your-client-email',
-    privateKey: 'your-private-key',
-  },
-  defaultLocale: 'default-language-in-sheet-header',
-});
-
-await importer.importTranslations();
-```
-
-### Configuration ⚙️
-
-The configuration object required for using the importer is as follows:
-
-#### Required 📝
-
-- **`credentials`**: Google Sheets API credentials:
-  - `sheetId`: The ID of your Google Spreadsheet (extracted from the URL).
-  - `clientEmail`: The email of the Google Sheets API client.
-  - `privateKey`: The private key associated with the client.
-- **`defaultLocale`**: The default locale/language specified in your Google Sheet header.
-
-#### Optional 🔧
-
-- **`headerStartRowNumber`**: Specifies the row number where the headers begin (if not at the top).
-- **`ignoredSheets`**: A list of sheets to exclude by title. By default, sheets without the `defaultLocale` in headers will be ignored.
-- **`importPath`**: Path to save exported translations from your sheet. This is the location where the exported translations will be saved. By default, it will use the current working directory (cwd). This option is only used when calling the `importTranslations` method.
-
-### Importer Methods 🛠️
-
-#### `getTranslations` 📝
-
-- **Description**: This function retrieves the translation data, which is structured by locale keys (such as "ko", "en", etc.). It collects all translations from the specified sheet, replaces any placeholders, and prepares them to be sent to the client in the response body. Each key corresponds to a language, and the value for each key is an object containing the translated text for that locale.
-
-- **Type**: Function
-- **Parameters**: None
-- **Returns**: An object where each key is a locale (e.g., "ko", "en"), and the value is the respective translation data for that locale.
-
-#### Example:
-
-If the headers in your Google Sheets are `["ko", "en", ...]`, the result returned by `getTranslations` will look like this:
-
-```ts
-{
-  "ko": {
-    "greeting": "안녕하세요",
-    "farewell": "안녕히 가세요"
-  },
-  "en": {
-    "greeting": "Hello",
-    "farewell": "Goodbye"
-  }
-
-  ...
-}
-```
-
-In this example:
-
-- `"ko"` contains the translations for Korean.
-- `"en"` contains the translations for English.
-  Each locale’s object contains key-value pairs for individual translations.
-
-#### `importTranslations` 📤
-
-- **Description**: This asynchronous function is used in a Node.js environment to export translations directly into your project. It is especially useful if your project includes server-side APIs (like Next.js API routes) and you need to update the locale JSON data in your project. It can be invoked to update or create the locale files within your project, ensuring that the translation data is synced with the local environment.
-
-- **Type**: Function
-- **Parameters**: None
-- **Returns**: `void`
-
-#### Example:
-
-If you call the `importTranslations` function, it will update or create JSON files in your project for each locale. The result could look like this:
+### Installation
 
-```ts
-// ko.json
-{
-  "greeting": "안녕하세요",
-  "farewell": "안녕히 가세요"
-}
-
-// en.json
-{
-  "greeting": "Hello",
-  "farewell": "Goodbye"
-}
+```shell
+npm install sheet-i18n
+npm install @sheet-i18n/cli -D
 ```
 
-### API Documentation 📚
-
-This package provides a streamlined way to export data using sheets API. It is designed to simplify the integration of spreadsheet data into your applications, particularly for translation workflows and internationalization (i18n).
-
-[Google Sheets API Documentation](https://developers.google.com/sheets/api)<br>
-[Google Auth Library](https://www.npmjs.com/package/google-auth-library)<br>
-[Google Spreadsheet](https://www.npmjs.com/package/google-spreadsheet)
-
-### Exporting Data Format 🗂️
-
-The exported translations will be saved in a format that is easy to use for localization purposes. Each translation is stored in its respective locale folder, with a structured format.
-
-</details>
-
----
-
-<details>
-<summary>⚛️ Frontend Translation Provider - sheet-i18n/react</summary>
+<details open>
+<summary><strong>⚛️ Frontend Translation Provider - sheet-i18n/react</strong></summary>
 
 ### `@sheet-i18n/react`
 
@@ -160,17 +37,20 @@ This package provides tools to handle translations in React applications using c
 
 ## ✨ 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:
 
@@ -192,13 +72,13 @@ Prepare locale JSON files:
 }
 ```
 
-#### 2. Initialize i18nStore
+### step 2. Initialize i18nStore
 
 this store will be used as a core translations module.
 
 ```tsx
-import en from './en.json';
 import ko from './ko.json';
+import en from './en.json';
 
 import { I18nStore } from '@sheet-i18n/react';
 
@@ -216,11 +96,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';
@@ -230,22 +112,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';
@@ -269,27 +153,28 @@ 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 = () => {
@@ -304,16 +189,54 @@ 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:
 
 ```tsx
+import ko from './locales/ko.json';
+import en from './locales/en.json';
+
 export const i18nStore = new I18nStore({
   supportedLocales: ['ko', 'en'],
   defaultLocale: 'ko',
@@ -327,6 +250,8 @@ export const i18nStore = new I18nStore({
   // dynamicLoaders: {
   //   ko: () => import('./ko.json'),
   //   en: () => import('./en.json'),
+  //   jp: () => import('./jp.json'),
+  //   cn: () => import('./cn.json'),
   // },
 });
 ```
@@ -360,7 +285,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.
 
@@ -496,7 +421,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.
@@ -524,7 +449,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.
@@ -560,39 +485,15 @@ 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
-
-This project is licensed under the ISC License.
-
-## 👤 Author
-
-**devAnderson**  
-[GitHub](https://github.com/chltjdrhd777)  
-[chltjdrhd777@gmail.com](mailto:chltjdrhd777@gmail.com)
-
 </details>
 
 ---
 
-<details>
-<summary>🔧 CLI for Automated Translation Management - @sheet-i18n/cli</summary>
+<details open>
+<summary><strong>
+🔧 CLI for easy bidirectional syncing - @sheet-i18n/cli</strong></summary>
 
-#### @sheet-i18n/cli
+### `@sheet-i18n/cli`
 
 A CLI tool for efficient translation management using Google Sheets, with a focus on developer experience (DX).
 
@@ -605,7 +506,7 @@ A CLI tool for efficient translation management using Google Sheets, with a focu
 
 ## Core Concepts 🌟
 
-### 😭 Traditional Translation Workflow
+### 😭 General Translation Workflow
 
 The traditional process of managing translations with Google Spreadsheets often includes these steps:
 
@@ -631,78 +532,80 @@ This CLI streamlines the process by shifting the focus to developers:
 
 With this approach, unnecessary back-and-forth is eliminated, and translations align seamlessly with code.
 
-## PreRequisite 📝
+## 🚀 Initial Setup with CLI
 
-This library is tightly integrated with the @sheet-i18n/react package, which provides the React components needed for rendering translations efficiently. As a result, you must set up **`@sheet-i18n/react`** in your project before using this CLI.
+<a id="initial-setup-anchor"></a>
 
-#### 1. Initialize i18n Store
+`@sheet-i18n/cli` provides a fully automated setup for React applications.  
+Once installed, you can bootstrap the required i18n context, store, and folder structure by simply running:
 
-This store will be used as a core translations module.
+```bash
+npx sheet-i18n init
+```
 
-```tsx
-import en from './en.json';
-import ko from './ko.json';
+This will automatically generate:
 
-import { I18nStore } from '@sheet-i18n/react';
+- A preconfigured `i18nStore` using `@sheet-i18n/react`
+- A ready-to-use `i18nContext.ts` that exports `IntlProvider`, `useTranslation`, and `getTranslation`
+- Example locale JSON files (e.g., `en.json`, `ko.json`)
+- The `sheet.config.json` file for managing your CLI behavior and Google Sheets credentials
 
-export const i18nStore = new I18nStore({
-  supportedLocales: ['ko', 'en'],
-  defaultLocale: 'ko',
-  localeSet: {
-    ko,
-    en,
-  },
-  typeSafe: false, // optional (default: true)
-});
-```
+> 💡 All files will be created in the recommended structure (e.g. `src/i18n`, `src/locales`), and safely skipped if they already exist.
 
-> 💡 **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.
->
-> ```tsx
-> // typeSafe: true
-> const YourComponent = () => {
->   // "useTranslation" shows the autocompletion suggestions
->   const { t } = useTranslation('header');
->
->   return (
->     <div>
->       {/* "t" function shows the autocompletion suggestions */}
->       <button>{t('login')}</button>
->     </div>
->   );
-> };
-> ```
+---
 
-#### 2. Create i18n Context
+### ✅ What You No Longer Have to Do Manually
 
-```tsx
-import { i18nStore } from './file-path-of-i18nStore-initiated';
-import { createI18nContext } from '@sheet-i18n/react';
+- You don’t need to manually initiate `I18nStore` or set up the React context.
+- You don’t need to manually prepare locale JSON templates.
+- You don’t need to manually configure `sheet.config.json`.
 
-export const { IntlProvider, useTranslation } = createI18nContext(i18nStore);
+Just run the init command and you’re ready to use `useTranslation()` in your components.
+
+---
+
+### 🗂️ Example Output:
+
+```bash
+📦 your-project/
+├── 📄 .gitignore                      # Automatically appends 'sheet.config.json' to ignore list
+├── 📄 sheet.config.json              # CLI configuration file (contains Google Sheet credentials & options)
+└── 📁 src/
+    └── 📁 i18n/
+        ├── 📄 i18nContext.tsx        # React context for IntlProvider, useTranslation, and getTranslation
+        ├── 📄 i18nStore.ts           # Initializes I18nStore with supported locales and translation data
+        ├── 📄 en.json                # Placeholder for English translation strings
+        └── 📄 ko.json                # Placeholder for Korean translation strings
 ```
 
-#### 3. Mount Intl Context Provider in your App
+✅ The CLI automatically creates this structure after running `npx sheet-i18n init`.  
+🛡️ If `sheet.config.json` or `src/i18n` already exist, the CLI will skip the creation of these files.
+
+after running `npx sheet-i18n init`, you can mount the IntlProvider in your app.
+
+#### Mount Intl Context Provider in your App
 
 ```tsx
 import React from 'react';
-import { IntlProvider } from './i18nContext';
+import I18nContextProvider from './i18n/i18nContext';
 
 const App = () => {
+  const [locale, setLocale] = useState('en');
+
   return (
-    <IntlProvider>
+    <I18nContextProvider currentLocale={locale}>
       <YourComponent />
-    </IntlProvider>
+    </I18nContextProvider>
   );
 };
 ```
 
-#### 4. Use Translations
+#### Use Translations
 
 ```tsx
+// YourComponent.tsx
 import React from 'react';
-import { useTranslation } from './i18nContext';
+import { useTranslation } from './i18n/i18nContext';
 
 const YourComponent = () => {
   const { t } = useTranslation('header');
@@ -716,31 +619,11 @@ const YourComponent = () => {
 };
 ```
 
-Follow the documentation for @sheet-i18n/react to ensure proper configuration.
-
-## Base workflow
-
-Install the CLI tool globally or as a dev dependency:
+### That's it! <br/>
 
-```shell
-npm install -g @sheet-i18n/cli
-```
-
-or
-
-```shell
-npm install --save-dev @sheet-i18n/cli
-```
-
-Initialize the CLI in your project:
-
-```shell
-npx sheet-i18n init
-```
+your translations are now ready to use in your application.
 
-After initialization, the **"sheet.config.json"** file will be created in the root of your project (and .gitignored automatically).
-
-### Configuration ⚙️
+### ⚙️ sheet.config.json
 
 The CLI requires a `sheet.config.json` file in the root of your project. Run `sheet-i18n init` to generate this file automatically.
 
@@ -760,26 +643,38 @@ Example `sheet.config.json`:
     "defaultLocale": "en",
     "supportedLocales": ["en", "fr", "es"],
     "ignoredSheets": ["BASE"],
-    "importPath": "./src/locales"
+    "importPath": "./src/locales",
+    "autoAppendFilePathColumn": {
+      "enabled": true,
+      "columnName": "__filePath",
+      "fullFilePath": false
+    }
   }
 }
 ```
 
-#### 1. File change monitoring configuration
+### 1. File change monitoring configuration
+
+| Option             | Type     | Required | Default                    | Description                                                                    |
+| ------------------ | -------- | -------- | -------------------------- | ------------------------------------------------------------------------------ |
+| `watchEntry`       | string   |          | "src"                      | Entry path to monitor file changes, relative to the current working directory. |
+| `detectExtensions` | string[] |          | ["jsx", "js", "tsx", "ts"] | List of file extensions to watch.                                              |
 
-- `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
 
-#### 2. Register command configuration
+### 📄 `googleSheetConfig` Options
 
-- **`googleSheetConfig (required)`**: Configuration for Google Sheets integration:
-  - **`spreadsheetId (required)`**: The ID of your Google Spreadsheet.
-  - **`credentials (required)`**: Contains `sheetId`, `clientEmail`, and `privateKey` for API authentication.
-  - **`defaultLocale (required)`**: Default language/locale used in the sheet header.
-  - **`supportedLocales(required)`**: List of locales supported in your sheet (default: [defaultLocale]).
-  - **headerStartRowNumber** (optional): Row number where headers start (default: 1).
-  - **ignoredSheets** (optional): Titles of sheets to exclude from the translation process.
-  - **importPath** (optional): Directory path to save exported translations based on the current working directory (default: `.`).
+| Option                     | Type     | Required | Default                                                                                                                | Description                                                                                                                                                                                                                                                                                                                                                                   |
+| -------------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `credentials.sheetId`      | string   | ✅       |                                                                                                                        | The same ID as `spreadsheetId` (for API auth).                                                                                                                                                                                                                                                                                                                                |
+| `credentials.clientEmail`  | string   | ✅       |                                                                                                                        | Client email from your Google Service Account credentials.                                                                                                                                                                                                                                                                                                                    |
+| `credentials.privateKey`   | string   | ✅       |                                                                                                                        | Private key from your Google Service Account credentials.                                                                                                                                                                                                                                                                                                                     |
+| `defaultLocale`            | string   | ✅       |                                                                                                                        | The default language/locale used in the sheet's header row.                                                                                                                                                                                                                                                                                                                   |
+| `supportedLocales`         | string[] | ✅       |                                                                                                                        | Array of all supported locale codes (e.g., `["en", "ko"]`).                                                                                                                                                                                                                                                                                                                   |
+| `headerStartRowNumber`     | number   |          | 1                                                                                                                      | Row number where sheet headers begin.                                                                                                                                                                                                                                                                                                                                         |
+| `ignoredSheets`            | string[] |          |                                                                                                                        | Titles of sheets to ignore during register/import (e.g., `["BASE"]`).                                                                                                                                                                                                                                                                                                         |
+| `importPath`               | string   |          | current working directory                                                                                              | Directory path to export translation JSON files.                                                                                                                                                                                                                                                                                                                              |
+| `autoAppendFilePathColumn` | object   |          | <strong>enabled: </strong>true<br/><strong>columnName: </strong>"\_\_filePath"<br/><strong>fullFilePath:</strong>false | Configuration for appending reference file path to each translation row. This indicates where the translation key is located in your source code.<br><br>- `enabled`: Whether to append the file path column<br>- `columnName`: Column name to use for file path<br>- `fullFilePath`: Show full path or mask intermediate folders (e.g., `"*******/folder1/folder2/file.ts"`) |
 
 ## Commands
 
@@ -829,13 +724,18 @@ function Component (){
 }
 ```
 
-The _watch result_ is
+The _watched result_ is
 
 ```shell
-📝 Translations Store:
- {
-  environment: Set(1) { 'over', 'under' }
- }
+Detected Translations:
+
+📄 [Sheet Title]: environment
+ - over
+ - under
+
+# You can proceed using the shortcuts below:
+ - Press <Shift + R> to register the detected changes.
+ - Press <Ctrl + C> to cancel the watch command.
 ```
 
 </br>
@@ -843,7 +743,7 @@ The _watch result_ is
 ### 📤 register
 
 ```shell
-sheet-i18n register [options]
+npx sheet-i18n register [options]
 ```
 
 Registers translation data to Google Sheets.
@@ -860,15 +760,18 @@ Registers translation data to Google Sheets.
 
 - `-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`).
-  - **`total`**: Scans the entire directory for all translation keys and updates the spreadsheet, regardless of Git changes.  
-    **Default**: `diff`
+  - **`total`**: Scans the entire directory for all translation keys and updates the spreadsheet, regardless of Git changes.
+  - **`select`**: User selection mode which allows you to choose the sheets to register.
+
+- **Default**: `diff`
 
 ---
 
-#### Detailed description of the `scope` option:
+#### 📄 Detailed description of the `scope` option:
 
-##### Scope: `diff`
+#### Scope: `diff`
 
 - The CLI identifies changes in translation keys by comparing the current state of the codebase with the latest Git commit.
 - It only processes translation keys added, removed, or modified since the last commit.
@@ -881,9 +784,7 @@ Registers translation data to Google Sheets.
 npx sheet-i18n register
 ```
 
----
-
-##### Scope: `total`
+#### Scope: `total`
 
 - The CLI scans the entire specified directory for all translation keys from the directory path you provide.
 - This is useful for full synchronization, ensuring all keys are registered in the spreadsheet.
@@ -892,7 +793,23 @@ npx sheet-i18n register
 ##### Example:
 
 ```shell
-sheet-i18n register --scope total
+npx sheet-i18n register --scope total
+```
+
+#### Scope: `select`
+
+- The CLI prompts you to manually select which sheets you want to update.
+
+- Once the selection is made, only the chosen sheets will have their translation data updated in the Google Spreadsheet.
+
+- This mode is especially useful for partial updates, allowing you to skip scanning the entire directory and focus on specific sheets.
+
+- It’s also helpful in cases where you’ve committed changes without registering translation data during development — instead of syncing all translations, you can update only the relevant sheets as needed.
+
+##### Example:
+
+```shell
+npx sheet-i18n register --scope select
 ```
 
 </br>
@@ -921,8 +838,125 @@ The configuration of export command is based on **`sheet.config.json`** on your
 }
 ```
 
+</details>
+
 ---
 
+<details open>
+<summary><strong>🌍 Server Export Function - sheet-i18n/importer</strong></summary>
+
+### `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
+import { googleSheetImporter } from 'sheet-i18n/importer';
+
+const importer = await googleSheetImporter({
+  credentials: {
+    sheetId: 'your-google-sheet-id',
+    clientEmail: 'your-client-email',
+    privateKey: 'your-private-key',
+  },
+  defaultLocale: 'default-language-in-sheet-header',
+});
+
+await importer.importTranslations();
+```
+
+### Configuration ⚙️
+
+The configuration object required for using the importer is as follows:
+
+#### Required 📝
+
+- **`credentials`**: Google Sheets API credentials:
+  - `sheetId`: The ID of your Google Spreadsheet (extracted from the URL).
+  - `clientEmail`: The email of the Google Sheets API client.
+  - `privateKey`: The private key associated with the client.
+- **`defaultLocale`**: The default locale/language specified in your Google Sheet header.
+
+#### Optional 🔧
+
+- **`headerStartRowNumber`**: Specifies the row number where the headers begin (if not at the top).
+- **`ignoredSheets`**: A list of sheets to exclude by title. By default, sheets without the `defaultLocale` in headers will be ignored.
+- **`importPath`**: Path to save exported translations from your sheet. This is the location where the exported translations will be saved. By default, it will use the current working directory (cwd). This option is only used when calling the `importTranslations` method.
+
+### Importer Methods 🛠️
+
+#### `getTranslations` 📝
+
+- **Description**: This function retrieves the translation data, which is structured by locale keys (such as "ko", "en", etc.). It collects all translations from the specified sheet, replaces any placeholders, and prepares them to be sent to the client in the response body. Each key corresponds to a language, and the value for each key is an object containing the translated text for that locale.
+
+- **Type**: Function
+- **Parameters**: None
+- **Returns**: An object where each key is a locale (e.g., "ko", "en"), and the value is the respective translation data for that locale.
+
+#### Example:
+
+If the headers in your Google Sheets are `["ko", "en", ...]`, the result returned by `getTranslations` will look like this:
+
+```ts
+{
+  "ko": {
+    "greeting": "안녕하세요",
+    "farewell": "안녕히 가세요"
+  },
+  "en": {
+    "greeting": "Hello",
+    "farewell": "Goodbye"
+  }
+
+  ...
+}
+```
+
+In this example:
+
+- `"ko"` contains the translations for Korean.
+- `"en"` contains the translations for English.
+  Each locale’s object contains key-value pairs for individual translations.
+
+#### `importTranslations` 📤
+
+- **Description**: This asynchronous function is used in a Node.js environment to export translations directly into your project. It is especially useful if your project includes server-side APIs (like Next.js API routes) and you need to update the locale JSON data in your project. It can be invoked to update or create the locale files within your project, ensuring that the translation data is synced with the local environment.
+
+- **Type**: Function
+- **Parameters**: None
+- **Returns**: `void`
+
+#### Example:
+
+If you call the `importTranslations` function, it will update or create JSON files in your project for each locale. The result could look like this:
+
+```ts
+// ko.json
+{
+  "greeting": "안녕하세요",
+  "farewell": "안녕히 가세요"
+}
+
+// en.json
+{
+  "greeting": "Hello",
+  "farewell": "Goodbye"
+}
+```
+
+### API Documentation 📚
+
+This package provides a streamlined way to export data using sheets API. It is designed to simplify the integration of spreadsheet data into your applications, particularly for translation workflows and internationalization (i18n).
+
+[Google Sheets API Documentation](https://developers.google.com/sheets/api)<br>
+[Google Auth Library](https://www.npmjs.com/package/google-auth-library)<br>
+[Google Spreadsheet](https://www.npmjs.com/package/google-spreadsheet)
+
+### Exported Data Format 🗂️
+
+The exported translations will be saved in a format that is easy to use for localization purposes. Each translation is stored in its respective locale folder, with a structured format.
+
+</details>
+
 ## License 📜
 
 This project is licensed under the ISC License. See the LICENSE file for details.
@@ -930,5 +964,3 @@ This project is licensed under the ISC License. See the LICENSE file for details
 ## Author ✍️
 
 Created by [devAnderson](https://github.com/chltjdrhd777).
-
-</details>

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "sheet-i18n",
-  "version": "1.6.0",
+  "description": "All-in-one i18n toolchain: seamlessly integrate Google Sheets, CLI, and react-i18n for easy translation workflows.",
+  "version": "1.7.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/chltjdrhd777/sheet-i18n"
@@ -27,7 +28,14 @@
     "sheet-i18n",
     "spreadsheet",
     "i18n",
-    "translation"
+    "translation",
+    "internationalization",
+    "localization",
+    "i18n workflow",
+    "spreadsheet i18n",
+    "i18n management",
+    "translation management",
+    "google spreadsheet"
   ],
   "author": {
     "name": "devAnderson",
@@ -35,14 +43,15 @@
     "url": "https://github.com/chltjdrhd777"
   },
   "license": "ISC",
+  "homepage": "https://github.com/chltjdrhd777/sheet-i18n",
   "dependencies": {
-    "@sheet-i18n/react": "1.3.0",
-    "@sheet-i18n/importer": "1.6.0"
+    "@sheet-i18n/react": "1.4.1",
+    "@sheet-i18n/importer": "1.7.1"
   },
   "devDependencies": {
     "tsup": "^6.0.0",
     "typescript": "^5.0.0",
-    "@sheet-i18n/typescript-config": "1.6.0"
+    "@sheet-i18n/typescript-config": "1.7.1"
   },
   "scripts": {
     "build": "tsup",