@better-i18n/use-intl 0.1.6 → 0.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-i18n/use-intl",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Better i18n integration for use-intl (React, TanStack Start)",
   "license": "MIT",
   "repository": {
@@ -44,14 +44,21 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@better-i18n/core": "0.1.6"
+    "@better-i18n/core": "0.1.8"
   },
   "peerDependencies": {
     "react": ">=18.0.0",
-    "use-intl": ">=4.0.0"
+    "use-intl": ">=4.0.0",
+    "@tanstack/react-router": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/react-router": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/react": "^19.0.0",
+    "@tanstack/react-router": "^1.120.3",
     "react": "^19.0.0",
     "use-intl": "^4.7.0",
     "typescript": "~5.9.2"

package/src/components.tsx

@@ -1,12 +1,11 @@
 "use client";
 
 import type { ComponentProps, ReactNode } from "react";
-import { useBetterI18n } from "./context";
+import { useLocaleRouter } from "./hooks/useLocaleRouter";
+import { useLanguages } from "./hooks";
 
-export interface LanguageSwitcherProps extends Omit<
-  ComponentProps<"select">,
-  "value" | "onChange" | "children"
-> {
+export interface LanguageSwitcherProps
+  extends Omit<ComponentProps<"select">, "value" | "onChange" | "children"> {
   /**
    * Render function for custom option display
    */
@@ -15,6 +14,7 @@ export interface LanguageSwitcherProps extends Omit<
     name?: string;
     nativeName?: string;
     flagUrl?: string | null;
+    isDefault?: boolean;
   }) => ReactNode;
 
   /**
@@ -24,11 +24,14 @@ export interface LanguageSwitcherProps extends Omit<
 }
 
 /**
- * Pre-built language switcher component
+ * Pre-built language switcher component with router integration
+ *
+ * Uses useLocaleRouter() internally for proper SPA navigation.
+ * Locale changes trigger router navigation, which re-executes loaders.
  *
  * @example
  * ```tsx
- * // Basic usage
+ * // Basic usage - just works!
  * <LanguageSwitcher />
  *
  * // With custom styling
@@ -50,9 +53,10 @@ export function LanguageSwitcher({
   loadingLabel = "Loading...",
   ...props
 }: LanguageSwitcherProps) {
-  const { locale, setLocale, languages, isLoadingLanguages } = useBetterI18n();
+  const { locale, navigate, isReady } = useLocaleRouter();
+  const { languages } = useLanguages();
 
-  if (isLoadingLanguages) {
+  if (!isReady) {
     return (
       <select disabled {...props}>
         <option>{loadingLabel}</option>
@@ -61,11 +65,7 @@ export function LanguageSwitcher({
   }
 
   return (
-    <select
-      value={locale}
-      onChange={(e) => setLocale(e.target.value)}
-      {...props}
-    >
+    <select value={locale} onChange={(e) => navigate(e.target.value)} {...props}>
       {languages.map((lang) => (
         <option key={lang.code} value={lang.code}>
           {renderOption ? renderOption(lang) : lang.nativeName || lang.code}

package/src/context.tsx

@@ -13,18 +13,34 @@ export const BetterI18nContext = createContext<BetterI18nContextValue | null>(
 /**
  * Hook to access Better i18n context
  *
+ * Note: For locale switching, use useLocaleRouter() which integrates with TanStack Router.
+ *
  * @example
  * ```tsx
- * function LanguageSwitcher() {
- *   const { locale, setLocale, languages } = useBetterI18n()
+ * function LanguageInfo() {
+ *   const { locale, languages, isLoadingLanguages } = useBetterI18n()
+ *
+ *   if (isLoadingLanguages) return <div>Loading...</div>
+ *
+ *   return (
+ *     <div>
+ *       Current: {locale}
+ *       Available: {languages.map(l => l.code).join(', ')}
+ *     </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) => setLocale(e.target.value)}>
- *       {languages.map((lang) => (
- *         <option key={lang.code} value={lang.code}>
- *           {lang.nativeName}
- *         </option>
- *       ))}
+ *     <select value={locale} onChange={(e) => navigate(e.target.value)}>
+ *       {locales.map((loc) => <option key={loc} value={loc}>{loc}</option>)}
  *     </select>
  *   )
  * }

package/src/hooks/useLocaleRouter.ts

@@ -0,0 +1,147 @@
+"use client";
+
+import { useCallback, useMemo } from "react";
+import { useRouter, useLocation } from "@tanstack/react-router";
+import {
+  getLocaleFromPath,
+  replaceLocaleInPath,
+  addLocalePrefix,
+  type LocaleConfig,
+} from "@better-i18n/core";
+import { useBetterI18n } from "../context";
+
+/**
+ * Return type for useLocaleRouter hook
+ */
+export interface UseLocaleRouterReturn {
+  /**
+   * Current locale (extracted from URL or default)
+   */
+  locale: string;
+
+  /**
+   * Available locales from CDN manifest
+   */
+  locales: string[];
+
+  /**
+   * Default locale (no URL prefix)
+   */
+  defaultLocale: string;
+
+  /**
+   * Navigate to the same page with a new locale
+   * Uses TanStack Router's navigate() for proper SPA navigation
+   */
+  navigate: (locale: string) => void;
+
+  /**
+   * Get a localized path for link building
+   * @param path - The path to localize
+   * @param locale - Target locale (optional, uses current if not specified)
+   */
+  localePath: (path: string, locale?: string) => string;
+
+  /**
+   * Whether languages have been loaded from CDN
+   */
+  isReady: boolean;
+}
+
+/**
+ * Hook for router-integrated locale navigation
+ *
+ * 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
+ *
+ * @example
+ * ```tsx
+ * function LanguageSwitcher() {
+ *   const { locale, locales, navigate, isReady } = useLocaleRouter();
+ *
+ *   if (!isReady) return <Skeleton />;
+ *
+ *   return (
+ *     <select value={locale} onChange={(e) => navigate(e.target.value)}>
+ *       {locales.map((loc) => (
+ *         <option key={loc} value={loc}>{loc}</option>
+ *       ))}
+ *     </select>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Building localized links
+ * function Navigation() {
+ *   const { localePath } = useLocaleRouter();
+ *
+ *   return (
+ *     <nav>
+ *       <Link to={localePath('/about')}>About</Link>
+ *       <Link to={localePath('/contact', 'tr')}>İletişim (TR)</Link>
+ *     </nav>
+ *   );
+ * }
+ * ```
+ */
+export function useLocaleRouter(): UseLocaleRouterReturn {
+  const router = useRouter();
+  const location = useLocation();
+  const { languages, isLoadingLanguages } = useBetterI18n();
+
+  // Build config from CDN manifest
+  const config: LocaleConfig = 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)
+  const locale = useMemo(() => {
+    // If no languages loaded yet, extract from path manually
+    if (languages.length === 0) {
+      const segments = location.pathname.split("/").filter(Boolean);
+      const firstSegment = segments[0];
+      // Check if it looks like a locale code (2 letters)
+      if (firstSegment && /^[a-z]{2}$/i.test(firstSegment)) {
+        return firstSegment;
+      }
+      return "en"; // fallback
+    }
+    return getLocaleFromPath(location.pathname, config);
+  }, [location.pathname, config, languages]);
+
+  // Navigate to same page with new locale (SPA navigation!)
+  const navigate = useCallback(
+    (newLocale: string) => {
+      const newPath = replaceLocaleInPath(location.pathname, newLocale, config);
+      router.navigate({ to: newPath });
+    },
+    [location.pathname, config, router]
+  );
+
+  // Get localized path for links
+  const localePath = useCallback(
+    (path: string, targetLocale?: string) => {
+      const loc = targetLocale || locale;
+      return addLocalePrefix(path, loc, config);
+    },
+    [locale, config]
+  );
+
+  return {
+    locale,
+    locales: config.locales,
+    defaultLocale: config.defaultLocale,
+    navigate,
+    localePath,
+    isReady: !isLoadingLanguages && config.locales.length > 0,
+  };
+}

package/src/hooks.ts

@@ -3,7 +3,7 @@
 import { useBetterI18n } from "./context";
 
 /**
- * Hook to get available languages
+ * Hook to get available languages from CDN manifest
  *
  * @example
  * ```tsx
@@ -34,27 +34,41 @@ export function useLanguages() {
 }
 
 /**
- * Hook to get and set current locale
+ * Hook to get current locale (read-only)
+ *
+ * For locale switching with proper router navigation, use useLocaleRouter() instead.
  *
  * @example
  * ```tsx
- * function LocaleSwitcher() {
- *   const { locale, setLocale } = useLocale()
+ * function LocaleDisplay() {
+ *   const { locale, 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={() => setLocale(locale === 'en' ? 'tr' : 'en')}>
- *       Current: {locale}
+ *     <button onClick={() => navigate(locale === 'en' ? 'tr' : 'en')}>
+ *       Toggle: {locale}
  *     </button>
  *   )
  * }
  * ```
  */
 export function useLocale() {
-  const { locale, setLocale, isLoadingMessages } = useBetterI18n();
+  const { locale, isLoadingMessages } = useBetterI18n();
 
   return {
     locale,
-    setLocale,
     isLoading: isLoadingMessages,
   };
 }

package/src/index.ts

@@ -15,6 +15,10 @@ export {
   useTimeZone,
 } from "./hooks";
 
+// Router Integration (TanStack Router)
+export { useLocaleRouter } from "./hooks/useLocaleRouter";
+export type { UseLocaleRouterReturn } from "./hooks/useLocaleRouter";
+
 // Components
 export { LanguageSwitcher } from "./components";
 export type { LanguageSwitcherProps } from "./components";
@@ -26,5 +30,17 @@ export type {
   BetterI18nContextValue,
 } from "./types";
 
+// Re-export locale utilities from core (convenience)
+export {
+  extractLocale,
+  getLocaleFromPath,
+  hasLocalePrefix,
+  removeLocalePrefix,
+  addLocalePrefix,
+  replaceLocaleInPath,
+  createLocalePath,
+  type LocaleConfig,
+} from "@better-i18n/core";
+
 // Re-export commonly used use-intl components
 export { IntlProvider } from "use-intl";

package/src/middleware/index.ts

@@ -1,12 +1,11 @@
-// @ts-ignore - internal workspace dependency
+// @ts-expect-error - internal workspace dependency
 import { createMiddleware } from "@tanstack/react-router";
-// @ts-ignore - internal workspace dependency
+// @ts-expect-error - internal workspace dependency
 import { detectLocale, getLocales } from "@better-i18n/core";
-// @ts-ignore - internal workspace dependency
 import type { I18nMiddlewareConfig } from "@better-i18n/core";
 
 export function createBetterI18nMiddleware(config: I18nMiddlewareConfig) {
-  const { project, defaultLocale, detection = {} } = config;
+  const { project, defaultLocale, localePrefix = "as-needed", detection = {} } = config;
 
   const {
     cookie = true,
@@ -16,19 +15,37 @@ export function createBetterI18nMiddleware(config: I18nMiddlewareConfig) {
   } = detection;
 
   return createMiddleware().server(
-    async ({ next, request }: { next: any; request: any }) => {
+    async ({
+      next,
+      request,
+    }: {
+      next: (ctx: { context: { locale: string } }) => Promise<unknown>;
+      request: Request;
+    }) => {
       // 1. Fetch available locales from CDN (cached)
       const availableLocales = await getLocales({ project });
 
       // 2. Extract locale indicators
       const url = new URL(request.url);
-      const pathLocale = url.pathname.split("/")[1];
+      const pathSegment = url.pathname.split("/")[1];
+      const hasLocaleInPath =
+        !!pathSegment && availableLocales.includes(pathSegment);
 
       // Dynamic imports for TanStack Start server functions to avoid bundling them in client
-      // @ts-ignore - internal workspace dependency
-      const { getCookie, setCookie, getRequestHeader } =
-        // @ts-ignore - dynamic import type safety
-        await import("@tanstack/react-start/server");
+      const {
+        getCookie,
+        setCookie,
+        getRequestHeader,
+      }: {
+        getCookie: (name: string) => string | null;
+        setCookie: (
+          name: string,
+          value: string,
+          options: { path: string; maxAge: number; sameSite: string },
+        ) => void;
+        getRequestHeader: (name: string) => string | undefined;
+        // @ts-expect-error - optional runtime dependency
+      } = await import("@tanstack/react-start/server");
 
       const cookieLocale = cookie ? getCookie(cookieName) : null;
       const headerLocale = browserLanguage
@@ -39,13 +56,49 @@ export function createBetterI18nMiddleware(config: I18nMiddlewareConfig) {
       const result = detectLocale({
         project,
         defaultLocale,
-        pathLocale,
+        pathLocale: pathSegment,
         cookieLocale,
         headerLocale,
         availableLocales,
       });
 
-      // 4. Set cookie if needed (if enabled and changed)
+      // 4. Redirect if locale prefix is needed but missing
+      //    Skip API routes and paths that already have a locale prefix
+      const isApiRoute = url.pathname.startsWith("/api/");
+      if (
+        localePrefix !== "never" &&
+        !hasLocaleInPath &&
+        !isApiRoute &&
+        result.detectedFrom !== "path"
+      ) {
+        const shouldRedirect =
+          localePrefix === "always" ||
+          (localePrefix === "as-needed" && result.locale !== defaultLocale);
+
+        if (shouldRedirect) {
+          const redirectUrl = new URL(
+            `/${result.locale}${url.pathname}`,
+            url.origin,
+          );
+          redirectUrl.search = url.search;
+
+          // Build redirect response with locale cookie
+          const headers = new Headers({
+            Location: redirectUrl.toString(),
+          });
+
+          if (cookie && result.shouldSetCookie) {
+            headers.set(
+              "Set-Cookie",
+              `${cookieName}=${result.locale}; Path=/; Max-Age=${cookieMaxAge}; SameSite=Lax`,
+            );
+          }
+
+          return new Response(null, { status: 302, headers });
+        }
+      }
+
+      // 5. Set cookie if needed (non-redirect path)
       if (cookie && result.shouldSetCookie) {
         setCookie(cookieName, result.locale, {
           path: "/",
@@ -54,7 +107,7 @@ export function createBetterI18nMiddleware(config: I18nMiddlewareConfig) {
         });
       }
 
-      // 5. Pass locale to route context
+      // 6. Pass locale to route context
       return next({ context: { locale: result.locale } });
     },
   );

package/src/provider.tsx

@@ -2,13 +2,7 @@
 
 import { createI18nCore } from "@better-i18n/core";
 import type { LanguageOption } from "@better-i18n/core";
-import {
-  useCallback,
-  useEffect,
-  useMemo,
-  useState,
-  type ReactNode,
-} from "react";
+import { useEffect, useMemo, useState, type ReactNode } from "react";
 import { IntlProvider } from "use-intl";
 import { BetterI18nContext } from "./context.js";
 import type { BetterI18nProviderConfig, Messages } from "./types.js";
@@ -20,6 +14,9 @@ export interface BetterI18nProviderProps extends BetterI18nProviderConfig {
 /**
  * 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.
+ *
  * @example
  * ```tsx
  * // Basic usage (CSR - fetches messages on client)
@@ -34,15 +31,16 @@ export interface BetterI18nProviderProps extends BetterI18nProviderConfig {
  *   )
  * }
  *
- * // SSR usage (pre-loaded messages)
- * function App({ locale, messages }) {
+ * // TanStack Router SSR usage (pre-loaded messages from loader)
+ * function RootComponent() {
+ *   const { messages, locale } = Route.useLoaderData()
  *   return (
  *     <BetterI18nProvider
  *       project="acme/dashboard"
  *       locale={locale}
  *       messages={messages}
  *     >
- *       <MyComponent />
+ *       <Outlet />
  *     </BetterI18nProvider>
  *   )
  * }
@@ -51,37 +49,43 @@ export interface BetterI18nProviderProps extends BetterI18nProviderConfig {
 export function BetterI18nProvider({
   children,
   project,
-  locale: initialLocale,
-  messages: initialMessages,
+  locale: propLocale,
+  messages: propMessages,
   timeZone,
   now,
-  onLocaleChange,
   onError,
   cdnBaseUrl,
   debug,
   logLevel,
   fetch: customFetch,
 }: BetterI18nProviderProps) {
-  const [locale, setLocaleState] = useState(initialLocale);
-  const [messages, setMessages] = useState<Messages | undefined>(
-    initialMessages,
-  );
+  // Locale is controlled by props (from URL/router)
+  const locale = propLocale;
+  const [messages, setMessages] = useState<Messages | undefined>(propMessages);
   const [languages, setLanguages] = useState<LanguageOption[]>([]);
-  const [isLoadingMessages, setIsLoadingMessages] = useState(!initialMessages);
+  const [isLoadingMessages, setIsLoadingMessages] = useState(!propMessages);
   const [isLoadingLanguages, setIsLoadingLanguages] = useState(true);
 
+  // Sync messages when props change (e.g., from router navigation with new loader data)
+  useEffect(() => {
+    if (propMessages) {
+      setMessages(propMessages);
+      setIsLoadingMessages(false);
+    }
+  }, [propMessages]);
+
   // Create i18n core instance
   const i18nCore = useMemo(
     () =>
       createI18nCore({
         project,
-        defaultLocale: initialLocale,
+        defaultLocale: locale,
         cdnBaseUrl,
         debug,
         logLevel,
         fetch: customFetch,
       }),
-    [project, initialLocale, cdnBaseUrl, debug, logLevel, customFetch],
+    [project, locale, cdnBaseUrl, debug, logLevel, customFetch]
   );
 
   // Load languages on mount
@@ -110,10 +114,10 @@ export function BetterI18nProvider({
     };
   }, [i18nCore]);
 
-  // Load messages when locale changes (if not pre-loaded)
+  // Load messages when locale changes and no pre-loaded messages available
   useEffect(() => {
-    // Skip if we have initial messages for the current locale
-    if (initialMessages && locale === initialLocale) {
+    // Skip if we already have messages for this render
+    if (propMessages) {
       return;
     }
 
@@ -130,7 +134,7 @@ export function BetterI18nProvider({
       } catch (error) {
         console.error(
           `[better-i18n] Failed to load messages for locale "${locale}":`,
-          error,
+          error
         );
       } finally {
         if (!cancelled) {
@@ -144,35 +148,18 @@ export function BetterI18nProvider({
     return () => {
       cancelled = true;
     };
-  }, [locale, i18nCore, initialMessages, initialLocale]);
-
-  // Locale change handler
-  const setLocale = useCallback(
-    (newLocale: string) => {
-      setLocaleState(newLocale);
-      onLocaleChange?.(newLocale);
-    },
-    [onLocaleChange],
-  );
+  }, [locale, i18nCore, propMessages]);
 
-  // Context value
+  // Context value (read-only locale - use useLocaleRouter for navigation)
   const contextValue = useMemo(
     () => ({
       locale,
-      setLocale,
       languages,
       isLoadingLanguages,
       isLoadingMessages,
       project,
     }),
-    [
-      locale,
-      setLocale,
-      languages,
-      isLoadingLanguages,
-      isLoadingMessages,
-      project,
-    ],
+    [locale, languages, isLoadingLanguages, isLoadingMessages, project]
   );
 
   // Don't render until we have messages

package/src/server.ts

@@ -28,7 +28,7 @@ export async function getMessages(
     fetch: config.fetch,
   });
 
-  const messages = (await i18n.getMessages(config.locale)) as any;
+  const messages = (await i18n.getMessages(config.locale)) as Messages;
 
   // better-i18n convention: JSON matches exact namespace structure.
   // if CDN returns { "hero": { "title": "..." } }, use-intl expects exactly that

package/src/types.ts

@@ -33,11 +33,6 @@ export interface BetterI18nProviderConfig
    */
   now?: Date;
 
-  /**
-   * Callback when locale changes
-   */
-  onLocaleChange?: (locale: string) => void;
-
   /**
    * Error handler for missing translations
    */
@@ -46,25 +41,23 @@ export interface BetterI18nProviderConfig
 
 /**
  * Better i18n context value
+ *
+ * Note: Locale is read-only. Use useLocaleRouter().navigate() for locale changes
+ * to ensure proper router integration.
  */
 export interface BetterI18nContextValue {
   /**
-   * Current locale
+   * Current locale (read-only - use useLocaleRouter().navigate() to change)
    */
   locale: string;
 
   /**
-   * Change the current locale
-   */
-  setLocale: (locale: string) => void;
-
-  /**
-   * Available languages with metadata
+   * Available languages with metadata from CDN manifest
    */
   languages: LanguageOption[];
 
   /**
-   * Whether languages are still loading
+   * Whether languages are still loading from CDN
    */
   isLoadingLanguages: boolean;