@sheet-i18n/react 1.5.0-canary.4 → 1.5.0-canary.5

package/README.md

@@ -17,7 +17,7 @@ This package provides tools to handle translations in React applications using c
 ## 🚀 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.
 
@@ -454,6 +454,135 @@ 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.tsx
+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()
+);
+```
+
+#### **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)
+
 ## License 📜
 
 This project is licensed under the ISC License. See the LICENSE file for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sheet-i18n/react",
-  "version": "1.5.0-canary.4",
+  "version": "1.5.0-canary.5",
   "description": "i18n client logic based on react",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -33,7 +33,7 @@
   },
   "dependencies": {
     "@sheet-i18n/react-core": "1.5.0-canary.0",
-    "@sheet-i18n/react-client": "1.5.0-canary.1"
+    "@sheet-i18n/react-client": "1.5.0-canary.2"
   },
   "scripts": {
     "build": "tsup",