sheet-i18n 1.8.0-canary.1 → 1.8.0-canary.11

package/README.md

@@ -485,6 +485,128 @@ export default function App() {
 }
 ```
 
+## 🌐 Advanced Interpolation Strategies
+
+sheet-i18n provides advanced interpolation strategies for different rendering environments. These strategies ensure optimal performance and user experience across various deployment scenarios.
+
+### 🖥️ Client-Side Rendering (CSR) Interpolation
+
+For client-side applications, sheet-i18n offers `StorageBasedIntlProvider` with `LocaleStorageManager` to handle **persistent locale settings** and interpolation seamlessly.
+
+#### **What is Persistent Locale Settings?**
+
+The `StorageBasedIntlProvider` provides **persistent translation settings** that automatically remember and restore the user's language preference across browser sessions. This means:
+
+- **Session Persistence**: User's language choice persists even after closing and reopening the browser
+- **Cross-Tab Synchronization**: Language changes are synchronized across all open tabs/windows
+- **Automatic Restoration**: When users return to your app, their preferred language is automatically restored
+- **Fallback Handling**: If stored preferences are invalid, the system gracefully falls back to default settings
+
+#### **Setup for CSR Interpolation**
+
+```tsx
+// i18nContext.ts
+import { createI18nContext } from '@sheet-i18n/react';
+import { i18nStore } from './i18nStore';
+
+export const {
+  StorageBasedIntlProvider,
+  useTranslation,
+  getLocaleStorageManager,
+  useLocaleStorage,
+} = createI18nContext(i18nStore);
+
+// Create a storage manager
+// if you don't pass the storage service as an argument,
+// it automatically utilize "LocalStorage" as the storage service
+export const localeStorageManager = getLocaleStorageManager();
+```
+
+#### **Implementation Example**
+
+```tsx
+// App.tsx
+import React from 'react';
+import { StorageBasedIntlProvider, localeStorageManager } from './i18nContext';
+
+const App = () => {
+  return (
+    // StorageBasedIntlProvider automatically re-render
+    // if storage local data is changed
+    <StorageBasedIntlProvider storageManager={localeStorageManager}>
+      <YourApp />
+    </StorageBasedIntlProvider>
+  );
+};
+
+// Component with persistent locale switching
+const WelcomeComponent = () => {
+  const { t } = useTranslation('welcome');
+  const { locale } = useLocaleStorage(localeStorageManager);
+
+  return (
+    <div>
+      <h1>{t('welcome_message')}</h1>
+      <p>Current language: {locale}</p>
+
+      {/* Language change handler */}
+      <button onClick={() => localeStorageManager.setLocale('ko')}>
+        한국어
+      </button>
+      <button onClick={() => localeStorageManager.setLocale('en')}>
+        English
+      </button>
+    </div>
+  );
+};
+```
+
+#### **How Persistence Works**
+
+1. **Initial Load**: When the app starts, `StorageBasedIntlProvider` automatically checks for previously saved locale preferences
+2. **Automatic Restoration**: If a saved preference exists, it's automatically applied; otherwise, the default locale is used
+3. **Real-time Updates**: When users change the language, the new preference is immediately saved to storage and re-render the page
+
+#### **Custom Storage Service**
+
+For advanced use cases, you can implement custom storage services to control how locale preferences are persisted:
+
+```tsx
+// customStorageService.ts
+import { IStorageService } from '@sheet-i18n/react';
+
+export class CustomStorageService implements IStorageService<string> {
+  private storage = new Map<string, string>();
+
+  getItem(key: string): string {
+    // Retrieve persisted locale preference
+    return this.storage.get(key) || 'en';
+  }
+
+  setItem(key: string, value: string): boolean {
+    // Persist locale preference for cross-session memory
+    this.storage.set(key, value);
+    return true;
+  }
+
+  removeItem(key: string): boolean {
+    // Clear persisted locale preference
+    return this.storage.delete(key);
+  }
+
+  clear(): boolean {
+    // Clear all persisted preferences
+    this.storage.clear();
+    return true;
+  }
+}
+
+// Usage with custom persistence strategy
+const customStorageManager = getLocaleStorageManager(
+  new CustomStorageService()
+);
+```
+
 </details>
 
 ---
@@ -548,7 +670,7 @@ This will automatically generate:
 - 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
+- The `sheet.config.ts` file for managing your CLI behavior and Google Sheets credentials
 
 > 💡 All files will be created in the recommended structure (e.g. `src/i18n`, `src/locales`), and safely skipped if they already exist.
 
@@ -558,7 +680,7 @@ This will automatically generate:
 
 - 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`.
+- You don’t need to manually configure `sheet.config.ts`.
 
 Just run the init command and you’re ready to use `useTranslation()` in your components.
 
@@ -568,18 +690,18 @@ Just run the init command and you’re ready to use `useTranslation()` in your c
 
 ```bash
 📦 your-project/
-├── 📄 .gitignore                      # Automatically appends 'sheet.config.json' to ignore list
-├── 📄 sheet.config.json              # CLI configuration file (contains Google Sheet credentials & options)
+├── 📄 .gitignore                      # Automatically appends 'sheet.config.ts' to ignore list
+├── 📄 sheet.config.ts              # CLI configuration file (contains Google Sheet credentials & options)
 └── 📁 src/
     └── 📁 i18n/
-        ├── 📄 i18nContext.tsx        # React context for IntlProvider, useTranslation, and getTranslation
+        ├── 📄 i18nContext.ts        # 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
 ```
 
 ✅ 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.
+🛡️ If `sheet.config.ts` 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.
 
@@ -623,11 +745,11 @@ const YourComponent = () => {
 
 your translations are now ready to use in your application.
 
-### ⚙️ sheet.config.json
+### ⚙️ sheet.config.ts
 
-The CLI requires a `sheet.config.json` file in the root of your project. Run `sheet-i18n init` to generate this file automatically.
+The CLI requires a `sheet.config.ts` file in the root of your project. Run `sheet-i18n init` to generate this file automatically.
 
-Example `sheet.config.json`:
+Example `sheet.config.ts`:
 
 ```json
 {
@@ -684,7 +806,7 @@ Example `sheet.config.json`:
 npx sheet-i18n init
 ```
 
-Sets up the `sheet.config.json` file in your project. This configuration file is required for all other commands.
+Sets up the `sheet.config.ts` file in your project. This configuration file is required for all other commands.
 
 </br>
 
@@ -754,7 +876,7 @@ Registers translation data to Google Sheets.
 
 2. It updates rows and adds "translation" entries using the `GOOGLETRANSLATE` function supported by Google Spreadsheets for automated translations.
 
-3. After registering, it asks whether you want to update the locale JSON data locally. It then exports the JSON data to the `importPath` specified in `sheet.config.json` (default is the current working directory).
+3. After registering, it asks whether you want to update the locale JSON data locally. It then exports the JSON data to the `importPath` specified in `sheet.config.ts` (default is the current working directory).
 
 #### Options:
 
@@ -821,7 +943,7 @@ npx sheet-i18n import
 ```
 
 Exports translation data from Google Sheets to local export directory.
-The configuration of export command is based on **`sheet.config.json`** on your root.
+The configuration of export command is based on **`sheet.config.ts`** on your root.
 
 ```json
 {

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.8.0-canary.1",
+  "version": "1.8.0-canary.11",
   "repository": {
     "type": "git",
     "url": "https://github.com/chltjdrhd777/sheet-i18n"
@@ -45,16 +45,17 @@
   "license": "ISC",
   "homepage": "https://github.com/chltjdrhd777/sheet-i18n",
   "dependencies": {
-    "@sheet-i18n/importer": "1.8.0-canary.0",
-    "@sheet-i18n/react": "1.5.0-canary.1"
+    "@sheet-i18n/importer": "1.8.0-canary.2",
+    "@sheet-i18n/react": "1.5.0-canary.11"
   },
   "devDependencies": {
     "tsup": "^6.0.0",
     "typescript": "^5.0.0",
-    "@sheet-i18n/typescript-config": "1.8.0-canary.0"
+    "@sheet-i18n/typescript-config": "1.8.0-canary.2"
   },
   "scripts": {
     "build": "tsup",
-    "dev": "tsup --watch"
+    "dev": "tsup --watch",
+    "typecheck": "npx tsc --noEmit"
   }
 }