@better-i18n/use-intl 0.2.1 → 0.2.2

package/dist/context.d.ts

@@ -6,38 +6,25 @@ export declare const BetterI18nContext: import("react").Context<BetterI18nContex
 /**
  * Hook to access Better i18n context
  *
- * Note: For locale switching, use useLocaleRouter() which integrates with TanStack Router.
+ * Provides locale state, language list, and `setLocale()` for switching.
+ * For higher-level APIs, use `useLocale()` or `useLocaleRouter()`.
  *
  * @example
  * ```tsx
  * function LanguageInfo() {
- *   const { locale, languages, isLoadingLanguages } = useBetterI18n()
+ *   const { locale, setLocale, languages, isLoadingLanguages } = useBetterI18n()
  *
  *   if (isLoadingLanguages) return <div>Loading...</div>
  *
  *   return (
  *     <div>
- *       Current: {locale}
- *       Available: {languages.map(l => l.code).join(', ')}
+ *       <p>Current: {locale}</p>
+ *       <p>Available: {languages.map(l => l.code).join(', ')}</p>
+ *       <button onClick={() => setLocale('tr')}>Switch to Turkish</button>
  *     </div>
  *   )
  * }
  * ```
- *
- * @example
- * ```tsx
- * // For language switching with proper router navigation:
- * import { useLocaleRouter } from '@better-i18n/use-intl'
- *
- * function LanguageSwitcher() {
- *   const { locale, locales, navigate } = useLocaleRouter()
- *   return (
- *     <select value={locale} onChange={(e) => navigate(e.target.value)}>
- *       {locales.map((loc) => <option key={loc} value={loc}>{loc}</option>)}
- *     </select>
- *   )
- * }
- * ```
  */
 export declare function useBetterI18n(): BetterI18nContextValue;
 //# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEzD;;GAEG;AACH,eAAO,MAAM,iBAAiB,wDAE7B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,aAAa,IAAI,sBAAsB,CAUtD"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEzD;;GAEG;AACH,eAAO,MAAM,iBAAiB,wDAE7B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,IAAI,sBAAsB,CAUtD"}

package/dist/context.js

@@ -7,38 +7,25 @@ export const BetterI18nContext = createContext(null);
 /**
  * Hook to access Better i18n context
  *
- * Note: For locale switching, use useLocaleRouter() which integrates with TanStack Router.
+ * Provides locale state, language list, and `setLocale()` for switching.
+ * For higher-level APIs, use `useLocale()` or `useLocaleRouter()`.
  *
  * @example
  * ```tsx
  * function LanguageInfo() {
- *   const { locale, languages, isLoadingLanguages } = useBetterI18n()
+ *   const { locale, setLocale, languages, isLoadingLanguages } = useBetterI18n()
  *
  *   if (isLoadingLanguages) return <div>Loading...</div>
  *
  *   return (
  *     <div>
- *       Current: {locale}
- *       Available: {languages.map(l => l.code).join(', ')}
+ *       <p>Current: {locale}</p>
+ *       <p>Available: {languages.map(l => l.code).join(', ')}</p>
+ *       <button onClick={() => setLocale('tr')}>Switch to Turkish</button>
  *     </div>
  *   )
  * }
  * ```
- *
- * @example
- * ```tsx
- * // For language switching with proper router navigation:
- * import { useLocaleRouter } from '@better-i18n/use-intl'
- *
- * function LanguageSwitcher() {
- *   const { locale, locales, navigate } = useLocaleRouter()
- *   return (
- *     <select value={locale} onChange={(e) => navigate(e.target.value)}>
- *       {locales.map((loc) => <option key={loc} value={loc}>{loc}</option>)}
- *     </select>
- *   )
- * }
- * ```
  */
 export function useBetterI18n() {
     const context = useContext(BetterI18nContext);

package/dist/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAGlD;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,aAAa,CAC5C,IAAI,CACL,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,OAAO,GAAG,UAAU,CAAC,iBAAiB,CAAC,CAAC;IAE9C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,sEAAsE,CACvE,CAAC;IACJ,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAGlD;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,aAAa,CAC5C,IAAI,CACL,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,OAAO,GAAG,UAAU,CAAC,iBAAiB,CAAC,CAAC;IAE9C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,sEAAsE,CACvE,CAAC;IACJ,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/hooks/useLocaleRouter.d.ts

@@ -15,8 +15,9 @@ export interface UseLocaleRouterReturn {
      */
     defaultLocale: string;
     /**
-     * Navigate to the same page with a new locale
-     * Uses TanStack Router's navigate() for proper SPA navigation
+     * Navigate to the same page with a new locale.
+     * Uses TanStack Router navigation when available,
+     * falls back to context-based `setLocale()` otherwise.
      */
     navigate: (locale: string) => void;
     /**
@@ -31,16 +32,16 @@ export interface UseLocaleRouterReturn {
     isReady: boolean;
 }
 /**
- * Hook for router-integrated locale navigation
+ * Hook for locale navigation with automatic router detection.
  *
- * This hook provides a navigation-first approach to locale switching:
- * - Locale changes trigger proper router navigation
- * - Loaders re-execute with the new locale
- * - No state synchronization issues
- * - Works with TanStack Router's file-based routing
+ * When TanStack Router context is available, locale changes trigger
+ * proper SPA navigation. When no router is present (e.g., plain Vite
+ * apps), falls back to the provider's `setLocale()` for state-based
+ * locale switching.
  *
  * @example
  * ```tsx
+ * // Works in both router and non-router environments
  * function LanguageSwitcher() {
  *   const { locale, locales, navigate, isReady } = useLocaleRouter();
  *

package/dist/hooks/useLocaleRouter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useLocaleRouter.d.ts","sourceRoot":"","sources":["../../src/hooks/useLocaleRouter.ts"],"names":[],"mappings":"AAYA;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;IAElB;;OAEG;IACH,aAAa,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAEnC;;;;OAIG;IACH,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAEtD;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,eAAe,IAAI,qBAAqB,CAuDvD"}
+{"version":3,"file":"useLocaleRouter.d.ts","sourceRoot":"","sources":["../../src/hooks/useLocaleRouter.ts"],"names":[],"mappings":"AAYA;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;IAElB;;OAEG;IACH,aAAa,EAAE,MAAM,CAAC;IAEtB;;;;OAIG;IACH,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAEnC;;;;OAIG;IACH,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAEtD;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,eAAe,IAAI,qBAAqB,CA6FvD"}

package/dist/hooks/useLocaleRouter.js

@@ -4,16 +4,16 @@ import { useRouter, useLocation } from "@tanstack/react-router";
 import { getLocaleFromPath, replaceLocaleInPath, addLocalePrefix, } from "@better-i18n/core";
 import { useBetterI18n } from "../context.js";
 /**
- * Hook for router-integrated locale navigation
+ * Hook for locale navigation with automatic router detection.
  *
- * This hook provides a navigation-first approach to locale switching:
- * - Locale changes trigger proper router navigation
- * - Loaders re-execute with the new locale
- * - No state synchronization issues
- * - Works with TanStack Router's file-based routing
+ * When TanStack Router context is available, locale changes trigger
+ * proper SPA navigation. When no router is present (e.g., plain Vite
+ * apps), falls back to the provider's `setLocale()` for state-based
+ * locale switching.
  *
  * @example
  * ```tsx
+ * // Works in both router and non-router environments
  * function LanguageSwitcher() {
  *   const { locale, locales, navigate, isReady } = useLocaleRouter();
  *
@@ -45,16 +45,41 @@ import { useBetterI18n } from "../context.js";
  * ```
  */
 export function useLocaleRouter() {
-    const router = useRouter();
-    const location = useLocation();
-    const { languages, isLoadingLanguages } = useBetterI18n();
-    // Build config from CDN manifest
+    const { languages, isLoadingLanguages, localePrefix, locale: contextLocale, setLocale, } = useBetterI18n();
+    // Safely detect TanStack Router context.
+    // When no <RouterProvider> is in the tree, these hooks throw —
+    // we catch gracefully and fall back to context-based locale switching.
+    //
+    // This is safe because:
+    // - The router presence never changes during a component's lifecycle
+    // - React hook calls (useContext) inside useRouter/useLocation always execute
+    //   before any throw, so the hook count is consistent between renders
+    let router = null;
+    let location = null;
+    try {
+        router = useRouter();
+    }
+    catch {
+        // No TanStack Router context — will use context-based navigation
+    }
+    try {
+        location = useLocation();
+    }
+    catch {
+        // No TanStack Router context — will use context-based navigation
+    }
+    const hasRouter = router != null && location != null;
+    // Build config from CDN manifest — includes localePrefix for URL strategy
     const config = useMemo(() => ({
         locales: languages.map((lang) => lang.code),
         defaultLocale: languages.find((l) => l.isDefault)?.code || "en",
-    }), [languages]);
-    // Get effective locale from URL (handles default without prefix)
+        localePrefix,
+    }), [languages, localePrefix]);
+    // Get effective locale: from URL when router is available, from context otherwise
     const locale = useMemo(() => {
+        if (!hasRouter || !location) {
+            return contextLocale;
+        }
         // If no languages loaded yet, extract from path manually
         if (languages.length === 0) {
             const segments = location.pathname.split("/").filter(Boolean);
@@ -66,12 +91,18 @@ export function useLocaleRouter() {
             return "en"; // fallback
         }
         return getLocaleFromPath(location.pathname, config);
-    }, [location.pathname, config, languages]);
-    // Navigate to same page with new locale (SPA navigation!)
+    }, [hasRouter, location, config, languages, contextLocale]);
+    // Navigate: router-based SPA navigation or context-based state update
     const navigate = useCallback((newLocale) => {
-        const newPath = replaceLocaleInPath(location.pathname, newLocale, config);
-        router.navigate({ to: newPath });
-    }, [location.pathname, config, router]);
+        if (hasRouter && router && location) {
+            const newPath = replaceLocaleInPath(location.pathname, newLocale, config);
+            router.navigate({ to: newPath });
+        }
+        else {
+            // No router — update locale via provider state
+            setLocale(newLocale);
+        }
+    }, [hasRouter, location, config, router, setLocale]);
     // Get localized path for links
     const localePath = useCallback((path, targetLocale) => {
         const loc = targetLocale || locale;

package/dist/hooks/useLocaleRouter.js.map

@@ -1 +1 @@
-{"version":3,"file":"useLocaleRouter.js","sourceRoot":"","sources":["../../src/hooks/useLocaleRouter.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,GAEhB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAwC9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,UAAU,eAAe;IAC7B,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;IAC3B,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;IAC/B,MAAM,EAAE,SAAS,EAAE,kBAAkB,EAAE,GAAG,aAAa,EAAE,CAAC;IAE1D,iCAAiC;IACjC,MAAM,MAAM,GAAiB,OAAO,CAClC,GAAG,EAAE,CAAC,CAAC;QACL,OAAO,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC;QAC3C,aAAa,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,IAAI,IAAI,IAAI;KAChE,CAAC,EACF,CAAC,SAAS,CAAC,CACZ,CAAC;IAEF,iEAAiE;IACjE,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE;QAC1B,yDAAyD;QACzD,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAC9D,MAAM,YAAY,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;YACjC,mDAAmD;YACnD,IAAI,YAAY,IAAI,aAAa,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC;gBACrD,OAAO,YAAY,CAAC;YACtB,CAAC;YACD,OAAO,IAAI,CAAC,CAAC,WAAW;QAC1B,CAAC;QACD,OAAO,iBAAiB,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACtD,CAAC,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;IAE3C,0DAA0D;IAC1D,MAAM,QAAQ,GAAG,WAAW,CAC1B,CAAC,SAAiB,EAAE,EAAE;QACpB,MAAM,OAAO,GAAG,mBAAmB,CAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;QAC1E,MAAM,CAAC,QAAQ,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;IACnC,CAAC,EACD,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,CACpC,CAAC;IAEF,+BAA+B;IAC/B,MAAM,UAAU,GAAG,WAAW,CAC5B,CAAC,IAAY,EAAE,YAAqB,EAAE,EAAE;QACtC,MAAM,GAAG,GAAG,YAAY,IAAI,MAAM,CAAC;QACnC,OAAO,eAAe,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;IAC5C,CAAC,EACD,CAAC,MAAM,EAAE,MAAM,CAAC,CACjB,CAAC;IAEF,OAAO;QACL,MAAM;QACN,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,QAAQ;QACR,UAAU;QACV,OAAO,EAAE,CAAC,kBAAkB,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC;KAC1D,CAAC;AACJ,CAAC"}
+{"version":3,"file":"useLocaleRouter.js","sourceRoot":"","sources":["../../src/hooks/useLocaleRouter.ts"],"names":[],"mappings":"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"}

package/dist/hooks.d.ts

@@ -25,38 +25,27 @@ export declare function useLanguages(): {
     isLoading: boolean;
 };
 /**
- * Hook to get current locale (read-only)
- *
- * For locale switching with proper router navigation, use useLocaleRouter() instead.
+ * Hook to get current locale and switch between locales
  *
  * @example
  * ```tsx
  * function LocaleDisplay() {
- *   const { locale, isLoading } = useLocale()
+ *   const { locale, setLocale, isLoading } = useLocale()
  *
  *   if (isLoading) return <div>Loading...</div>
  *
- *   return <span>Current locale: {locale}</span>
- * }
- * ```
- *
- * @example
- * ```tsx
- * // For locale switching, use useLocaleRouter:
- * import { useLocaleRouter } from '@better-i18n/use-intl'
- *
- * function LocaleSwitcher() {
- *   const { locale, navigate } = useLocaleRouter()
  *   return (
- *     <button onClick={() => navigate(locale === 'en' ? 'tr' : 'en')}>
- *       Toggle: {locale}
- *     </button>
+ *     <div>
+ *       <span>Current: {locale}</span>
+ *       <button onClick={() => setLocale('tr')}>Switch to Turkish</button>
+ *     </div>
  *   )
  * }
  * ```
  */
 export declare function useLocale(): {
     locale: string;
+    setLocale: (locale: string) => void;
     isLoading: boolean;
 };
 export { useTranslations, useFormatter, useMessages, useNow, useTimeZone, useLocale as useIntlLocale, } from "use-intl";

package/dist/hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY;;;EAO3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,SAAS;;;EAOxB;AAGD,OAAO,EACL,eAAe,EACf,YAAY,EACZ,WAAW,EACX,MAAM,EACN,WAAW,EACX,SAAS,IAAI,aAAa,GAC3B,MAAM,UAAU,CAAC"}
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY;;;EAO3B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,SAAS;;;;EAQxB;AAGD,OAAO,EACL,eAAe,EACf,YAAY,EACZ,WAAW,EACX,MAAM,EACN,WAAW,EACX,SAAS,IAAI,aAAa,GAC3B,MAAM,UAAU,CAAC"}

package/dist/hooks.js

@@ -30,40 +30,29 @@ export function useLanguages() {
     };
 }
 /**
- * Hook to get current locale (read-only)
- *
- * For locale switching with proper router navigation, use useLocaleRouter() instead.
+ * Hook to get current locale and switch between locales
  *
  * @example
  * ```tsx
  * function LocaleDisplay() {
- *   const { locale, isLoading } = useLocale()
+ *   const { locale, setLocale, isLoading } = useLocale()
  *
  *   if (isLoading) return <div>Loading...</div>
  *
- *   return <span>Current locale: {locale}</span>
- * }
- * ```
- *
- * @example
- * ```tsx
- * // For locale switching, use useLocaleRouter:
- * import { useLocaleRouter } from '@better-i18n/use-intl'
- *
- * function LocaleSwitcher() {
- *   const { locale, navigate } = useLocaleRouter()
  *   return (
- *     <button onClick={() => navigate(locale === 'en' ? 'tr' : 'en')}>
- *       Toggle: {locale}
- *     </button>
+ *     <div>
+ *       <span>Current: {locale}</span>
+ *       <button onClick={() => setLocale('tr')}>Switch to Turkish</button>
+ *     </div>
  *   )
  * }
  * ```
  */
 export function useLocale() {
-    const { locale, isLoadingMessages } = useBetterI18n();
+    const { locale, setLocale, isLoadingMessages } = useBetterI18n();
     return {
         locale,
+        setLocale,
         isLoading: isLoadingMessages,
     };
 }

package/dist/hooks.js.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,EAAE,SAAS,EAAE,kBAAkB,EAAE,GAAG,aAAa,EAAE,CAAC;IAE1D,OAAO;QACL,SAAS;QACT,SAAS,EAAE,kBAAkB;KAC9B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,SAAS;IACvB,MAAM,EAAE,MAAM,EAAE,iBAAiB,EAAE,GAAG,aAAa,EAAE,CAAC;IAEtD,OAAO;QACL,MAAM;QACN,SAAS,EAAE,iBAAiB;KAC7B,CAAC;AACJ,CAAC;AAED,2CAA2C;AAC3C,OAAO,EACL,eAAe,EACf,YAAY,EACZ,WAAW,EACX,MAAM,EACN,WAAW,EACX,SAAS,IAAI,aAAa,GAC3B,MAAM,UAAU,CAAC"}
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,EAAE,SAAS,EAAE,kBAAkB,EAAE,GAAG,aAAa,EAAE,CAAC;IAE1D,OAAO;QACL,SAAS;QACT,SAAS,EAAE,kBAAkB;KAC9B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,SAAS;IACvB,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,iBAAiB,EAAE,GAAG,aAAa,EAAE,CAAC;IAEjE,OAAO;QACL,MAAM;QACN,SAAS;QACT,SAAS,EAAE,iBAAiB;KAC7B,CAAC;AACJ,CAAC;AAED,2CAA2C;AAC3C,OAAO,EACL,eAAe,EACf,YAAY,EACZ,WAAW,EACX,MAAM,EACN,WAAW,EACX,SAAS,IAAI,aAAa,GAC3B,MAAM,UAAU,CAAC"}

package/dist/provider.d.ts

@@ -5,28 +5,49 @@ export interface BetterI18nProviderProps extends BetterI18nProviderConfig {
     children: ReactNode;
     /** Pre-loaded languages from SSR loader — skips loading state on first render */
     initialLanguages?: LanguageOption[];
+    /**
+     * URL prefix strategy for locale codes.
+     * - `"as-needed"` (default): default locale has no URL prefix
+     * - `"always"`: all locales get a URL prefix (e.g., TanStack Router `$locale/` routes)
+     * @default "as-needed"
+     */
+    localePrefix?: "always" | "as-needed";
     /** Custom fallback when a message key is missing */
     getMessageFallback?: (info: {
         error: Error;
         key: string;
         namespace?: string;
     }) => string;
+    /**
+     * Called when locale changes via `setLocale()` (e.g., from `LocaleDropdown`).
+     * In router-based apps, use this to trigger URL navigation:
+     *
+     * @example
+     * ```tsx
+     * <BetterI18nProvider
+     *   project="acme/web"
+     *   locale={locale}
+     *   onLocaleChange={(newLocale) => {
+     *     navigate({ to: `/${newLocale}${pathname}` })
+     *   }}
+     * >
+     * ```
+     */
+    onLocaleChange?: (locale: string) => void;
 }
 /**
  * Provider component that combines Better i18n CDN with use-intl
  *
- * The locale is controlled externally (from URL/router). Use useLocaleRouter()
- * for locale switching with proper router integration.
+ * Manages locale state internally, enabling locale switching via
+ * `setLocale()` from `useLocale()` or `useLocaleRouter()`.
  *
  * @example
  * ```tsx
- * // Basic usage (CSR - fetches messages on client)
+ * // Plain Vite / React app (no router)
  * function App() {
  *   return (
- *     <BetterI18nProvider
- *       project="acme/dashboard"
- *       locale="en"
- *     >
+ *     <BetterI18nProvider project="acme/dashboard" locale="en">
+ *       <LocaleDropdown />
  *       <MyComponent />
  *     </BetterI18nProvider>
  *   )
@@ -47,5 +68,5 @@ export interface BetterI18nProviderProps extends BetterI18nProviderConfig {
  * }
  * ```
  */
-export declare function BetterI18nProvider({ children, project, locale: propLocale, messages: propMessages, timeZone, now, onError, cdnBaseUrl, debug, logLevel, fetch: customFetch, storage, staticData, fetchTimeout, retryCount, initialLanguages, getMessageFallback: customGetMessageFallback, }: BetterI18nProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function BetterI18nProvider({ children, project, locale: propLocale, messages: propMessages, timeZone, now, onError, cdnBaseUrl, debug, logLevel, fetch: customFetch, storage, staticData, fetchTimeout, retryCount, initialLanguages, localePrefix, getMessageFallback: customGetMessageFallback, onLocaleChange, }: BetterI18nProviderProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAwC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAG7E,OAAO,KAAK,EAAE,wBAAwB,EAAY,MAAM,YAAY,CAAC;AAErE,MAAM,WAAW,uBAAwB,SAAQ,wBAAwB;IACvE,QAAQ,EAAE,SAAS,CAAC;IACpB,iFAAiF;IACjF,gBAAgB,CAAC,EAAE,cAAc,EAAE,CAAC;IACpC,oDAAoD;IACpD,kBAAkB,CAAC,EAAE,CAAC,IAAI,EAAE;QAC1B,KAAK,EAAE,KAAK,CAAC;QACb,GAAG,EAAE,MAAM,CAAC;QACZ,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,KAAK,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,QAAQ,EACR,OAAO,EACP,MAAM,EAAE,UAAU,EAClB,QAAQ,EAAE,YAAY,EACtB,QAAQ,EACR,GAAG,EACH,OAAO,EACP,UAAU,EACV,KAAK,EACL,QAAQ,EACR,KAAK,EAAE,WAAW,EAClB,OAAO,EACP,UAAU,EACV,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAAE,wBAAwB,GAC7C,EAAE,uBAAuB,2CAoJzB"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAqD,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAG1F,OAAO,KAAK,EAAE,wBAAwB,EAAY,MAAM,YAAY,CAAC;AAErE,MAAM,WAAW,uBAAwB,SAAQ,wBAAwB;IACvE,QAAQ,EAAE,SAAS,CAAC;IACpB,iFAAiF;IACjF,gBAAgB,CAAC,EAAE,cAAc,EAAE,CAAC;IACpC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,QAAQ,GAAG,WAAW,CAAC;IACtC,oDAAoD;IACpD,kBAAkB,CAAC,EAAE,CAAC,IAAI,EAAE;QAC1B,KAAK,EAAE,KAAK,CAAC;QACb,GAAG,EAAE,MAAM,CAAC;QACZ,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,KAAK,MAAM,CAAC;IACb;;;;;;;;;;;;;;OAcG;IACH,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,QAAQ,EACR,OAAO,EACP,MAAM,EAAE,UAAU,EAClB,QAAQ,EAAE,YAAY,EACtB,QAAQ,EACR,GAAG,EACH,OAAO,EACP,UAAU,EACV,KAAK,EACL,QAAQ,EACR,KAAK,EAAE,WAAW,EAClB,OAAO,EACP,UAAU,EACV,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,YAA0B,EAC1B,kBAAkB,EAAE,wBAAwB,EAC5C,cAAc,GACf,EAAE,uBAAuB,2CAsKzB"}

package/dist/provider.js

@@ -1,24 +1,22 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createI18nCore } from "@better-i18n/core";
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { IntlProvider } from "use-intl";
 import { BetterI18nContext } from "./context.js";
 /**
  * Provider component that combines Better i18n CDN with use-intl
  *
- * The locale is controlled externally (from URL/router). Use useLocaleRouter()
- * for locale switching with proper router integration.
+ * Manages locale state internally, enabling locale switching via
+ * `setLocale()` from `useLocale()` or `useLocaleRouter()`.
  *
  * @example
  * ```tsx
- * // Basic usage (CSR - fetches messages on client)
+ * // Plain Vite / React app (no router)
  * function App() {
  *   return (
- *     <BetterI18nProvider
- *       project="acme/dashboard"
- *       locale="en"
- *     >
+ *     <BetterI18nProvider project="acme/dashboard" locale="en">
+ *       <LocaleDropdown />
  *       <MyComponent />
  *     </BetterI18nProvider>
  *   )
@@ -39,9 +37,20 @@ import { BetterI18nContext } from "./context.js";
  * }
  * ```
  */
-export function BetterI18nProvider({ children, project, locale: propLocale, messages: propMessages, timeZone, now, onError, cdnBaseUrl, debug, logLevel, fetch: customFetch, storage, staticData, fetchTimeout, retryCount, initialLanguages, getMessageFallback: customGetMessageFallback, }) {
-    // Locale is controlled by props (from URL/router)
-    const locale = propLocale;
+export function BetterI18nProvider({ children, project, locale: propLocale, messages: propMessages, timeZone, now, onError, cdnBaseUrl, debug, logLevel, fetch: customFetch, storage, staticData, fetchTimeout, retryCount, initialLanguages, localePrefix = "as-needed", getMessageFallback: customGetMessageFallback, onLocaleChange, }) {
+    // Internal locale state — enables non-router apps to switch locale
+    // via setLocale() without needing URL-based navigation.
+    const [managedLocale, setManagedLocale] = useState(propLocale);
+    // Sync when the external prop changes (e.g., router navigation updates propLocale)
+    useEffect(() => {
+        setManagedLocale(propLocale);
+    }, [propLocale]);
+    const locale = managedLocale;
+    // setLocale: updates internal state + notifies parent via callback
+    const setLocale = useCallback((newLocale) => {
+        setManagedLocale(newLocale);
+        onLocaleChange?.(newLocale);
+    }, [onLocaleChange]);
     // Track the locale that propMessages was originally provided for.
     // In SSR apps, propMessages comes from a one-time loader (script tag / SSR side-channel)
     // and stays frozen at the initial locale. When the user SPA-navigates to a new locale,
@@ -123,14 +132,15 @@ export function BetterI18nProvider({ children, project, locale: propLocale, mess
             cancelled = true;
         };
     }, [locale, i18nCore, propMessages]);
-    // Context value (read-only locale - use useLocaleRouter for navigation)
     const contextValue = useMemo(() => ({
         locale,
+        setLocale,
         languages,
         isLoadingLanguages,
         isLoadingMessages,
         project,
-    }), [locale, languages, isLoadingLanguages, isLoadingMessages, project]);
+        localePrefix,
+    }), [locale, setLocale, languages, isLoadingLanguages, isLoadingMessages, project, localePrefix]);
     if (!messages) {
         // Render children with empty messages instead of blanking the screen.
         // This converts a full DOM structural mismatch (null vs full tree)

package/dist/provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.tsx"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -34,14 +34,21 @@ export interface BetterI18nProviderConfig extends Omit<I18nCoreConfig, "defaultL
 /**
  * Better i18n context value
  *
- * Note: Locale is read-only. Use useLocaleRouter().navigate() for locale changes
- * to ensure proper router integration.
+ * Use `setLocale()` for locale switching. In router-based apps,
+ * the provider's `onLocaleChange` callback handles navigation.
  */
 export interface BetterI18nContextValue {
     /**
-     * Current locale (read-only - use useLocaleRouter().navigate() to change)
+     * Current locale
      */
     locale: string;
+    /**
+     * Change the active locale.
+     * Updates internal state and triggers message loading.
+     * In router-based apps, also fires the `onLocaleChange` callback
+     * so the parent can handle URL navigation.
+     */
+    setLocale: (locale: string) => void;
     /**
      * Available languages with metadata from CDN manifest
      */
@@ -58,6 +65,12 @@ export interface BetterI18nContextValue {
      * Project identifier
      */
     project: string;
+    /**
+     * URL prefix strategy for locale codes.
+     * - `"as-needed"`: default locale has no URL prefix
+     * - `"always"`: all locales get a URL prefix (e.g., TanStack Router `$locale/`)
+     */
+    localePrefix: "always" | "as-needed";
 }
 /**
  * Server-side configuration for getMessages

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AAC5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7C;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,cAAc,CAAC,OAAO,YAAY,CAAC,CAAC,UAAU,CAAC,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,wBACf,SAAQ,IAAI,CAAC,cAAc,EAAE,eAAe,CAAC;IAC7C;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAEpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,GAAG,CAAC,EAAE,IAAI,CAAC;IAEX;;OAEG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC,OAAO,YAAY,CAAC,CAAC,SAAS,CAAC,CAAC;CAC1D;AAED;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,SAAS,EAAE,cAAc,EAAE,CAAC;IAE5B;;OAEG;IACH,kBAAkB,EAAE,OAAO,CAAC;IAE5B;;OAEG;IACH,iBAAiB,EAAE,OAAO,CAAC;IAE3B;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,cAAc;IACvD;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AAC5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7C;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,cAAc,CAAC,OAAO,YAAY,CAAC,CAAC,UAAU,CAAC,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,wBACf,SAAQ,IAAI,CAAC,cAAc,EAAE,eAAe,CAAC;IAC7C;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAEpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,GAAG,CAAC,EAAE,IAAI,CAAC;IAEX;;OAEG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC,OAAO,YAAY,CAAC,CAAC,SAAS,CAAC,CAAC;CAC1D;AAED;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;;;OAKG;IACH,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAEpC;;OAEG;IACH,SAAS,EAAE,cAAc,EAAE,CAAC;IAE5B;;OAEG;IACH,kBAAkB,EAAE,OAAO,CAAC;IAE5B;;OAEG;IACH,iBAAiB,EAAE,OAAO,CAAC;IAE3B;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,YAAY,EAAE,QAAQ,GAAG,WAAW,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,cAAc;IACvD;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-i18n/use-intl",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Better i18n integration for use-intl (React, TanStack Start)",
   "license": "MIT",
   "repository": {