@sheet-i18n/react-client 1.4.1 → 1.5.0-canary.1

package/dist/index.d.mts

@@ -1,6 +1,32 @@
+import { I18nStore } from '@sheet-i18n/react-core';
+import { ObserverManager } from '@sheet-i18n/shared-utils';
 import { MessageDescriptor, IntlShape } from 'react-intl';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { I18nStore } from '@sheet-i18n/react-core';
+
+interface IStorageService<V extends string> {
+    getItem(key: string): V;
+    setItem(key: string, value: V): boolean;
+    removeItem(key: string): boolean;
+    clear(): boolean;
+}
+/**
+ * locale storage manager
+ * implements ILocaleStorageManager (injected StorageService)
+ */
+interface ILocaleStorageManager<TSupportedLocales extends readonly string[]> {
+    getLocale(): TSupportedLocales[number];
+    setLocale(locale: TSupportedLocales[number]): void;
+}
+declare class LocaleStorageManager<TSupportedLocales extends readonly string[], TLocaleSet extends Partial<Record<TSupportedLocales[number], Record<string, any>>>, TTypeSafe extends boolean = false> implements ILocaleStorageManager<TSupportedLocales> {
+    private readonly storageService;
+    private readonly i18nStore;
+    private readonly localeStorageKey;
+    observerManager: ObserverManager<TSupportedLocales[number]>;
+    constructor(storageService: IStorageService<TSupportedLocales[number]>, i18nStore: I18nStore<TSupportedLocales, TLocaleSet, TTypeSafe>, localeStorageKey?: string);
+    private initializeCurrentLocale;
+    getLocale: () => TSupportedLocales[number];
+    setLocale: (locale: TSupportedLocales[number]) => void;
+}
 
 type UseIntlParams<D = MessageDescriptor> = Parameters<IntlShape['$t']> extends [D, ...infer R] ? [...R, Omit<D, 'id'>] : never;
 type ExtendedUseIntlParams<D = MessageDescriptor> = UseIntlParams<D> extends [infer A, infer B, ...infer Rest] ? A extends Record<string, infer V> ? [Record<string, V | React.ReactNode>, B, ...Rest] : [A, B, ...Rest] : UseIntlParams<D>;
@@ -39,13 +65,26 @@ type IntlProviderProps<TSupportedLocales extends readonly string[], TLocaleSet e
     children: React.ReactNode;
 };
 
+declare function useLocaleStorage<TSupportedLocales extends readonly string[], TLocaleSet extends Partial<Record<TSupportedLocales[number], Record<string, any>>>, TTypeSafe extends boolean = false>(localeStorageManager: LocaleStorageManager<TSupportedLocales, TLocaleSet, TTypeSafe>): {
+    locale: TSupportedLocales[number];
+};
+
+interface StorageBasedIntlProviderProps<TSupportedLocales extends readonly string[], TLocaleSet extends Partial<Record<TSupportedLocales[number], Record<string, any>>>, TTypeSafe extends boolean = false> {
+    i18nStore: I18nStore<TSupportedLocales, TLocaleSet, TTypeSafe>;
+    storageManager: LocaleStorageManager<TSupportedLocales, TLocaleSet, TTypeSafe>;
+    children: React.ReactNode;
+}
+
 declare function createI18nContext<TSupportedLocales extends readonly string[], TLocaleSet extends Partial<Record<TSupportedLocales[number], Record<string, any>>>, TTypeSafe extends boolean = false>(i18nStore: I18nStore<TSupportedLocales, TLocaleSet, TTypeSafe>): {
     IntlProvider: ({ currentLocale, children, }: Omit<IntlProviderProps<TSupportedLocales, TLocaleSet>, "currentLocale" | "i18nStore"> & {
         currentLocale?: string;
         children?: React.ReactNode;
     }) => react_jsx_runtime.JSX.Element;
+    StorageBasedIntlProvider: ({ storageManager, children, }: Omit<StorageBasedIntlProviderProps<TSupportedLocales, TLocaleSet, TTypeSafe>, "i18nStore">) => react_jsx_runtime.JSX.Element;
     useTranslation: <TSheetTitle extends TTypeSafe extends true ? keyof TLocaleSet[TSupportedLocales[number]] extends never ? string : keyof TLocaleSet[TSupportedLocales[number]] : string>(sheetTitle: TSheetTitle) => UseTranslationReturn<TSupportedLocales, TLocaleSet, TTypeSafe, TSheetTitle>;
     getTranslation: <TSheetTitle extends TTypeSafe extends true ? keyof TLocaleSet[TSupportedLocales[number]] extends never ? string : keyof TLocaleSet[TSupportedLocales[number]] : string>(sheetTitle: TSheetTitle) => GetTranslationReturn<TSupportedLocales, TLocaleSet, TTypeSafe, TSheetTitle>;
+    getLocaleStorageManager: (storageService?: IStorageService<string>) => LocaleStorageManager<TSupportedLocales, TLocaleSet, TTypeSafe>;
+    useLocaleStorage: typeof useLocaleStorage;
 };
 
 export { createI18nContext };

package/dist/index.d.ts

@@ -1,6 +1,32 @@
+import { I18nStore } from '@sheet-i18n/react-core';
+import { ObserverManager } from '@sheet-i18n/shared-utils';
 import { MessageDescriptor, IntlShape } from 'react-intl';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { I18nStore } from '@sheet-i18n/react-core';
+
+interface IStorageService<V extends string> {
+    getItem(key: string): V;
+    setItem(key: string, value: V): boolean;
+    removeItem(key: string): boolean;
+    clear(): boolean;
+}
+/**
+ * locale storage manager
+ * implements ILocaleStorageManager (injected StorageService)
+ */
+interface ILocaleStorageManager<TSupportedLocales extends readonly string[]> {
+    getLocale(): TSupportedLocales[number];
+    setLocale(locale: TSupportedLocales[number]): void;
+}
+declare class LocaleStorageManager<TSupportedLocales extends readonly string[], TLocaleSet extends Partial<Record<TSupportedLocales[number], Record<string, any>>>, TTypeSafe extends boolean = false> implements ILocaleStorageManager<TSupportedLocales> {
+    private readonly storageService;
+    private readonly i18nStore;
+    private readonly localeStorageKey;
+    observerManager: ObserverManager<TSupportedLocales[number]>;
+    constructor(storageService: IStorageService<TSupportedLocales[number]>, i18nStore: I18nStore<TSupportedLocales, TLocaleSet, TTypeSafe>, localeStorageKey?: string);
+    private initializeCurrentLocale;
+    getLocale: () => TSupportedLocales[number];
+    setLocale: (locale: TSupportedLocales[number]) => void;
+}
 
 type UseIntlParams<D = MessageDescriptor> = Parameters<IntlShape['$t']> extends [D, ...infer R] ? [...R, Omit<D, 'id'>] : never;
 type ExtendedUseIntlParams<D = MessageDescriptor> = UseIntlParams<D> extends [infer A, infer B, ...infer Rest] ? A extends Record<string, infer V> ? [Record<string, V | React.ReactNode>, B, ...Rest] : [A, B, ...Rest] : UseIntlParams<D>;
@@ -39,13 +65,26 @@ type IntlProviderProps<TSupportedLocales extends readonly string[], TLocaleSet e
     children: React.ReactNode;
 };
 
+declare function useLocaleStorage<TSupportedLocales extends readonly string[], TLocaleSet extends Partial<Record<TSupportedLocales[number], Record<string, any>>>, TTypeSafe extends boolean = false>(localeStorageManager: LocaleStorageManager<TSupportedLocales, TLocaleSet, TTypeSafe>): {
+    locale: TSupportedLocales[number];
+};
+
+interface StorageBasedIntlProviderProps<TSupportedLocales extends readonly string[], TLocaleSet extends Partial<Record<TSupportedLocales[number], Record<string, any>>>, TTypeSafe extends boolean = false> {
+    i18nStore: I18nStore<TSupportedLocales, TLocaleSet, TTypeSafe>;
+    storageManager: LocaleStorageManager<TSupportedLocales, TLocaleSet, TTypeSafe>;
+    children: React.ReactNode;
+}
+
 declare function createI18nContext<TSupportedLocales extends readonly string[], TLocaleSet extends Partial<Record<TSupportedLocales[number], Record<string, any>>>, TTypeSafe extends boolean = false>(i18nStore: I18nStore<TSupportedLocales, TLocaleSet, TTypeSafe>): {
     IntlProvider: ({ currentLocale, children, }: Omit<IntlProviderProps<TSupportedLocales, TLocaleSet>, "currentLocale" | "i18nStore"> & {
         currentLocale?: string;
         children?: React.ReactNode;
     }) => react_jsx_runtime.JSX.Element;
+    StorageBasedIntlProvider: ({ storageManager, children, }: Omit<StorageBasedIntlProviderProps<TSupportedLocales, TLocaleSet, TTypeSafe>, "i18nStore">) => react_jsx_runtime.JSX.Element;
     useTranslation: <TSheetTitle extends TTypeSafe extends true ? keyof TLocaleSet[TSupportedLocales[number]] extends never ? string : keyof TLocaleSet[TSupportedLocales[number]] : string>(sheetTitle: TSheetTitle) => UseTranslationReturn<TSupportedLocales, TLocaleSet, TTypeSafe, TSheetTitle>;
     getTranslation: <TSheetTitle extends TTypeSafe extends true ? keyof TLocaleSet[TSupportedLocales[number]] extends never ? string : keyof TLocaleSet[TSupportedLocales[number]] : string>(sheetTitle: TSheetTitle) => GetTranslationReturn<TSupportedLocales, TLocaleSet, TTypeSafe, TSheetTitle>;
+    getLocaleStorageManager: (storageService?: IStorageService<string>) => LocaleStorageManager<TSupportedLocales, TLocaleSet, TTypeSafe>;
+    useLocaleStorage: typeof useLocaleStorage;
 };
 
 export { createI18nContext };

package/dist/index.js

@@ -43,14 +43,14 @@ __export(src_exports, {
 module.exports = __toCommonJS(src_exports);
 
 // src/createI18nContext.tsx
-var import_shared_utils4 = require("@sheet-i18n/shared-utils");
+var import_shared_utils5 = require("@sheet-i18n/shared-utils");
 var import_react_core = require("@sheet-i18n/react-core");
 
-// src/IntlProvider.tsx
+// src/Provider/IntlProvider.tsx
 var import_react_intl2 = require("react-intl");
 var import_react2 = require("react");
 
-// src/useDynamicLocale.ts
+// src/hooks/useDynamicLocale.ts
 var import_shared_utils2 = require("@sheet-i18n/shared-utils");
 var import_react = require("react");
 
@@ -122,7 +122,7 @@ var IntlInstanceCache = class _IntlInstanceCache {
 };
 var intlInstanceCache = IntlInstanceCache.init();
 
-// src/useDynamicLocale.ts
+// src/hooks/useDynamicLocale.ts
 function useDynamicLocale(useDynamicLocaleProps) {
   const { i18nStore } = useDynamicLocaleProps != null ? useDynamicLocaleProps : {};
   const currentLocale = i18nStore == null ? void 0 : i18nStore.getCurrentLocale();
@@ -154,7 +154,7 @@ ${err}`);
   };
 }
 
-// src/IntlProvider.tsx
+// src/Provider/IntlProvider.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
 function IntlProvider({
   i18nStore,
@@ -183,8 +183,7 @@ function useIntlLocale({
   i18nStore,
   currentLocale
 }) {
-  var _a;
-  const locale = (_a = currentLocale != null ? currentLocale : detectClientLanguage(i18nStore)) != null ? _a : i18nStore.defaultLocale;
+  const locale = currentLocale || detectClientLanguage(i18nStore) || i18nStore.defaultLocale;
   i18nStore.setCurrentLocale(locale);
   (0, import_react2.useEffect)(() => {
     i18nStore.setCurrentLocale(locale);
@@ -248,7 +247,7 @@ var TranslationService = class {
   }
 };
 
-// src/useTranslation.ts
+// src/hooks/useTranslation.ts
 function useTranslation({
   sheetTitle,
   i18nStore
@@ -275,7 +274,7 @@ var InvalidI18nContextStateError = class extends import_errors.CustomError {
 var IsNotInstanceOfI18nStoreError = class extends import_errors.CustomError {
 };
 
-// src/getTranslation.ts
+// src/hooks/getTranslation.ts
 function getTranslation({
   sheetTitle,
   i18nStore
@@ -319,10 +318,176 @@ function getTranslation({
   return { t };
 }
 
-// src/createI18nContext.tsx
+// src/Service/StorageService.ts
+var import_shared_utils4 = require("@sheet-i18n/shared-utils");
+var StorageService = class {
+  constructor(storage) {
+    this.storage = null;
+    this.isClientSide = typeof window !== "undefined";
+    if (storage) {
+      this.storage = this.validateStorage(storage);
+    } else if (this.isClientSide) {
+      this.storage = this.initializeWindowLocalStorage();
+    }
+  }
+  validateStorage(storage) {
+    const requiredMethods = [
+      "getItem",
+      "setItem",
+      "removeItem",
+      "clear"
+    ];
+    try {
+      for (const method of requiredMethods) {
+        if (typeof storage[method] !== "function") {
+          throw new Error(
+            `Invalid storage object: missing required method '${method}'`
+          );
+        }
+      }
+      return storage;
+    } catch (error) {
+      console.error(error);
+      return null;
+    }
+  }
+  initializeWindowLocalStorage() {
+    try {
+      const testKey = "__storage_test__";
+      localStorage.setItem(testKey, "test");
+      localStorage.removeItem(testKey);
+      return localStorage;
+    } catch (error) {
+      console.warn("Window LocalStorage is not available:", error);
+      return null;
+    }
+  }
+  getItem(key) {
+    if (!this.storage || !key) {
+      return "";
+    }
+    try {
+      return this.storage.getItem(key);
+    } catch (error) {
+      console.error(`Failed to get item with key "${key}":`, error);
+      return "";
+    }
+  }
+  setItem(key, value) {
+    if (!this.storage || !key) {
+      return false;
+    }
+    try {
+      this.storage.setItem(key, value);
+      return true;
+    } catch (error) {
+      console.error(`Failed to set item with key "${key}":`, error);
+      return false;
+    }
+  }
+  removeItem(key) {
+    if (!this.storage || !key) {
+      return false;
+    }
+    try {
+      this.storage.removeItem(key);
+      return true;
+    } catch (error) {
+      console.error(`Failed to remove item with key "${key}":`, error);
+      return false;
+    }
+  }
+  clear() {
+    if (!this.storage) {
+      return false;
+    }
+    try {
+      this.storage.clear();
+      return true;
+    } catch (error) {
+      console.error("Failed to clear storage:", error);
+      return false;
+    }
+  }
+};
+var LocaleStorageManager = class {
+  constructor(storageService, i18nStore, localeStorageKey = "sheet-i18n-locale") {
+    this.storageService = storageService;
+    this.i18nStore = i18nStore;
+    this.localeStorageKey = localeStorageKey;
+    this.observerManager = new import_shared_utils4.ObserverManager();
+    this.initializeCurrentLocale = () => {
+      var _a, _b;
+      if (this.storageService && this.i18nStore.currentLocale) {
+        this.storageService.setItem(
+          this.localeStorageKey,
+          this.i18nStore.currentLocale
+        );
+      }
+      (_b = (_a = this.i18nStore) == null ? void 0 : _a.observerManager) == null ? void 0 : _b.addListener({
+        listenerId: this.localeStorageKey,
+        listener: (newLocale) => {
+          this.storageService.setItem(this.localeStorageKey, newLocale);
+        }
+      });
+    };
+    this.getLocale = () => {
+      const stored = this.storageService.getItem(this.localeStorageKey);
+      return stored != null ? stored : "";
+    };
+    this.setLocale = (locale) => {
+      this.storageService.setItem(this.localeStorageKey, locale);
+      this.observerManager.notify(locale);
+    };
+    this.initializeCurrentLocale();
+  }
+};
+var getLocaleStorageManager = (i18nStore, storage) => {
+  const localeStorageService = new StorageService(storage);
+  const localeStorageManager = new LocaleStorageManager(
+    localeStorageService,
+    i18nStore
+  );
+  return localeStorageManager;
+};
+
+// src/hooks/useLocaleStorage.ts
+var import_react3 = require("react");
+var LISTENER_ID = "LOCALE_STORAGE_LISTENER_ID";
+function useLocaleStorage(localeStorageManager) {
+  var _a;
+  const [locale, setLocale] = (0, import_react3.useState)((_a = localeStorageManager == null ? void 0 : localeStorageManager.getLocale) == null ? void 0 : _a.call(localeStorageManager));
+  (0, import_react3.useEffect)(() => {
+    var _a2;
+    (_a2 = localeStorageManager == null ? void 0 : localeStorageManager.observerManager) == null ? void 0 : _a2.addListener({
+      listenerId: LISTENER_ID,
+      listener: (newLocale) => {
+        setLocale(newLocale);
+      }
+    });
+    return () => {
+      var _a3;
+      (_a3 = localeStorageManager == null ? void 0 : localeStorageManager.observerManager) == null ? void 0 : _a3.removeListener(LISTENER_ID);
+    };
+  }, []);
+  return { locale };
+}
+
+// src/Provider/StorageBasedIntlProvider.tsx
 var import_jsx_runtime2 = require("react/jsx-runtime");
+function StorageBasedIntlProvider({
+  i18nStore,
+  storageManager,
+  children
+}) {
+  const { locale } = useLocaleStorage(storageManager);
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(IntlProvider, { currentLocale: locale, i18nStore, children });
+}
+
+// src/createI18nContext.tsx
+var import_jsx_runtime3 = require("react/jsx-runtime");
 function createI18nContext(i18nStore) {
-  if (import_shared_utils4.validator.isNullish(i18nStore)) {
+  if (import_shared_utils5.validator.isNullish(i18nStore)) {
     throw new InvalidI18nContextStateError(
       "\u26A0\uFE0F no i18nStore provided. To use createI18nContext, you must provide an i18nStore as a parameter"
     );
@@ -335,7 +500,7 @@ function createI18nContext(i18nStore) {
   const IntlProviderImpl = ({
     currentLocale,
     children
-  }) => /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+  }) => /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
     IntlProvider,
     {
       currentLocale,
@@ -343,12 +508,29 @@ function createI18nContext(i18nStore) {
       children
     }
   );
+  const StorageBasedIntlProviderImpl = ({
+    storageManager,
+    children
+  }) => /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+    StorageBasedIntlProvider,
+    {
+      i18nStore,
+      storageManager,
+      children
+    }
+  );
   const useTranslationImpl = (sheetTitle) => useTranslation({ sheetTitle, i18nStore });
   const getTranslationImpl = (sheetTitle) => getTranslation({ sheetTitle, i18nStore });
+  const getLocaleStorageManagerImpl = (storageService) => {
+    return getLocaleStorageManager(i18nStore, storageService);
+  };
   return {
     IntlProvider: IntlProviderImpl,
+    StorageBasedIntlProvider: StorageBasedIntlProviderImpl,
     useTranslation: useTranslationImpl,
-    getTranslation: getTranslationImpl
+    getTranslation: getTranslationImpl,
+    getLocaleStorageManager: getLocaleStorageManagerImpl,
+    useLocaleStorage
   };
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/index.mjs

@@ -23,11 +23,11 @@ var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
 import { validator as validator4 } from "@sheet-i18n/shared-utils";
 import { I18nStore } from "@sheet-i18n/react-core";
 
-// src/IntlProvider.tsx
+// src/Provider/IntlProvider.tsx
 import { IntlProvider as ReactIntlProvider } from "react-intl";
 import { useEffect } from "react";
 
-// src/useDynamicLocale.ts
+// src/hooks/useDynamicLocale.ts
 import { validator as validator2 } from "@sheet-i18n/shared-utils";
 import { useLayoutEffect, useState } from "react";
 
@@ -99,7 +99,7 @@ var IntlInstanceCache = class _IntlInstanceCache {
 };
 var intlInstanceCache = IntlInstanceCache.init();
 
-// src/useDynamicLocale.ts
+// src/hooks/useDynamicLocale.ts
 function useDynamicLocale(useDynamicLocaleProps) {
   const { i18nStore } = useDynamicLocaleProps != null ? useDynamicLocaleProps : {};
   const currentLocale = i18nStore == null ? void 0 : i18nStore.getCurrentLocale();
@@ -131,7 +131,7 @@ ${err}`);
   };
 }
 
-// src/IntlProvider.tsx
+// src/Provider/IntlProvider.tsx
 import { jsx } from "react/jsx-runtime";
 function IntlProvider({
   i18nStore,
@@ -160,8 +160,7 @@ function useIntlLocale({
   i18nStore,
   currentLocale
 }) {
-  var _a;
-  const locale = (_a = currentLocale != null ? currentLocale : detectClientLanguage(i18nStore)) != null ? _a : i18nStore.defaultLocale;
+  const locale = currentLocale || detectClientLanguage(i18nStore) || i18nStore.defaultLocale;
   i18nStore.setCurrentLocale(locale);
   useEffect(() => {
     i18nStore.setCurrentLocale(locale);
@@ -225,7 +224,7 @@ var TranslationService = class {
   }
 };
 
-// src/useTranslation.ts
+// src/hooks/useTranslation.ts
 function useTranslation({
   sheetTitle,
   i18nStore
@@ -252,7 +251,7 @@ var InvalidI18nContextStateError = class extends CustomError {
 var IsNotInstanceOfI18nStoreError = class extends CustomError {
 };
 
-// src/getTranslation.ts
+// src/hooks/getTranslation.ts
 function getTranslation({
   sheetTitle,
   i18nStore
@@ -296,8 +295,174 @@ function getTranslation({
   return { t };
 }
 
-// src/createI18nContext.tsx
+// src/Service/StorageService.ts
+import { ObserverManager } from "@sheet-i18n/shared-utils";
+var StorageService = class {
+  constructor(storage) {
+    this.storage = null;
+    this.isClientSide = typeof window !== "undefined";
+    if (storage) {
+      this.storage = this.validateStorage(storage);
+    } else if (this.isClientSide) {
+      this.storage = this.initializeWindowLocalStorage();
+    }
+  }
+  validateStorage(storage) {
+    const requiredMethods = [
+      "getItem",
+      "setItem",
+      "removeItem",
+      "clear"
+    ];
+    try {
+      for (const method of requiredMethods) {
+        if (typeof storage[method] !== "function") {
+          throw new Error(
+            `Invalid storage object: missing required method '${method}'`
+          );
+        }
+      }
+      return storage;
+    } catch (error) {
+      console.error(error);
+      return null;
+    }
+  }
+  initializeWindowLocalStorage() {
+    try {
+      const testKey = "__storage_test__";
+      localStorage.setItem(testKey, "test");
+      localStorage.removeItem(testKey);
+      return localStorage;
+    } catch (error) {
+      console.warn("Window LocalStorage is not available:", error);
+      return null;
+    }
+  }
+  getItem(key) {
+    if (!this.storage || !key) {
+      return "";
+    }
+    try {
+      return this.storage.getItem(key);
+    } catch (error) {
+      console.error(`Failed to get item with key "${key}":`, error);
+      return "";
+    }
+  }
+  setItem(key, value) {
+    if (!this.storage || !key) {
+      return false;
+    }
+    try {
+      this.storage.setItem(key, value);
+      return true;
+    } catch (error) {
+      console.error(`Failed to set item with key "${key}":`, error);
+      return false;
+    }
+  }
+  removeItem(key) {
+    if (!this.storage || !key) {
+      return false;
+    }
+    try {
+      this.storage.removeItem(key);
+      return true;
+    } catch (error) {
+      console.error(`Failed to remove item with key "${key}":`, error);
+      return false;
+    }
+  }
+  clear() {
+    if (!this.storage) {
+      return false;
+    }
+    try {
+      this.storage.clear();
+      return true;
+    } catch (error) {
+      console.error("Failed to clear storage:", error);
+      return false;
+    }
+  }
+};
+var LocaleStorageManager = class {
+  constructor(storageService, i18nStore, localeStorageKey = "sheet-i18n-locale") {
+    this.storageService = storageService;
+    this.i18nStore = i18nStore;
+    this.localeStorageKey = localeStorageKey;
+    this.observerManager = new ObserverManager();
+    this.initializeCurrentLocale = () => {
+      var _a, _b;
+      if (this.storageService && this.i18nStore.currentLocale) {
+        this.storageService.setItem(
+          this.localeStorageKey,
+          this.i18nStore.currentLocale
+        );
+      }
+      (_b = (_a = this.i18nStore) == null ? void 0 : _a.observerManager) == null ? void 0 : _b.addListener({
+        listenerId: this.localeStorageKey,
+        listener: (newLocale) => {
+          this.storageService.setItem(this.localeStorageKey, newLocale);
+        }
+      });
+    };
+    this.getLocale = () => {
+      const stored = this.storageService.getItem(this.localeStorageKey);
+      return stored != null ? stored : "";
+    };
+    this.setLocale = (locale) => {
+      this.storageService.setItem(this.localeStorageKey, locale);
+      this.observerManager.notify(locale);
+    };
+    this.initializeCurrentLocale();
+  }
+};
+var getLocaleStorageManager = (i18nStore, storage) => {
+  const localeStorageService = new StorageService(storage);
+  const localeStorageManager = new LocaleStorageManager(
+    localeStorageService,
+    i18nStore
+  );
+  return localeStorageManager;
+};
+
+// src/hooks/useLocaleStorage.ts
+import { useEffect as useEffect2, useState as useState2 } from "react";
+var LISTENER_ID = "LOCALE_STORAGE_LISTENER_ID";
+function useLocaleStorage(localeStorageManager) {
+  var _a;
+  const [locale, setLocale] = useState2((_a = localeStorageManager == null ? void 0 : localeStorageManager.getLocale) == null ? void 0 : _a.call(localeStorageManager));
+  useEffect2(() => {
+    var _a2;
+    (_a2 = localeStorageManager == null ? void 0 : localeStorageManager.observerManager) == null ? void 0 : _a2.addListener({
+      listenerId: LISTENER_ID,
+      listener: (newLocale) => {
+        setLocale(newLocale);
+      }
+    });
+    return () => {
+      var _a3;
+      (_a3 = localeStorageManager == null ? void 0 : localeStorageManager.observerManager) == null ? void 0 : _a3.removeListener(LISTENER_ID);
+    };
+  }, []);
+  return { locale };
+}
+
+// src/Provider/StorageBasedIntlProvider.tsx
 import { jsx as jsx2 } from "react/jsx-runtime";
+function StorageBasedIntlProvider({
+  i18nStore,
+  storageManager,
+  children
+}) {
+  const { locale } = useLocaleStorage(storageManager);
+  return /* @__PURE__ */ jsx2(IntlProvider, { currentLocale: locale, i18nStore, children });
+}
+
+// src/createI18nContext.tsx
+import { jsx as jsx3 } from "react/jsx-runtime";
 function createI18nContext(i18nStore) {
   if (validator4.isNullish(i18nStore)) {
     throw new InvalidI18nContextStateError(
@@ -312,7 +477,7 @@ function createI18nContext(i18nStore) {
   const IntlProviderImpl = ({
     currentLocale,
     children
-  }) => /* @__PURE__ */ jsx2(
+  }) => /* @__PURE__ */ jsx3(
     IntlProvider,
     {
       currentLocale,
@@ -320,12 +485,29 @@ function createI18nContext(i18nStore) {
       children
     }
   );
+  const StorageBasedIntlProviderImpl = ({
+    storageManager,
+    children
+  }) => /* @__PURE__ */ jsx3(
+    StorageBasedIntlProvider,
+    {
+      i18nStore,
+      storageManager,
+      children
+    }
+  );
   const useTranslationImpl = (sheetTitle) => useTranslation({ sheetTitle, i18nStore });
   const getTranslationImpl = (sheetTitle) => getTranslation({ sheetTitle, i18nStore });
+  const getLocaleStorageManagerImpl = (storageService) => {
+    return getLocaleStorageManager(i18nStore, storageService);
+  };
   return {
     IntlProvider: IntlProviderImpl,
+    StorageBasedIntlProvider: StorageBasedIntlProviderImpl,
     useTranslation: useTranslationImpl,
-    getTranslation: getTranslationImpl
+    getTranslation: getTranslationImpl,
+    getLocaleStorageManager: getLocaleStorageManagerImpl,
+    useLocaleStorage
   };
 }
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sheet-i18n/react-client",
-  "version": "1.4.1",
+  "version": "1.5.0-canary.1",
   "description": "a client package for react modules used by sheet-i18n",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -25,20 +25,20 @@
   },
   "license": "ISC",
   "dependencies": {
-    "@sheet-i18n/errors": "1.7.1",
-    "@sheet-i18n/shared-utils": "1.7.1",
-    "@sheet-i18n/react-core": "1.4.1"
+    "@sheet-i18n/shared-utils": "1.8.0-canary.0",
+    "@sheet-i18n/errors": "1.8.0-canary.0",
+    "@sheet-i18n/react-core": "1.5.0-canary.0"
   },
   "devDependencies": {
     "@types/react": "^19.0.2",
     "@types/react-dom": "^19.0.2",
     "react": "^18.2.0",
     "react-intl": "^7.0.4",
-    "@sheet-i18n/typescript-config": "1.7.1"
+    "@sheet-i18n/typescript-config": "1.8.0-canary.0"
   },
   "peerDependencies": {
-    "react": "^18 || ^19",
-    "react-dom": "^18 || ^19",
+    "react": "^18 || ^19 || ^20 || ^21",
+    "react-dom": "^18 || ^19 || ^20 || ^21",
     "react-intl": "^7.0.4"
   },
   "scripts": {