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

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>
 
 ---
@@ -572,7 +694,7 @@ Just run the init command and you’re ready to use `useTranslation()` in your c
 ├── 📄 sheet.config.json              # 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

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.10",
   "repository": {
     "type": "git",
     "url": "https://github.com/chltjdrhd777/sheet-i18n"
@@ -45,13 +45,13 @@
   "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.1",
+    "@sheet-i18n/react": "1.5.0-canary.10"
   },
   "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.1"
   },
   "scripts": {
     "build": "tsup",