@better-i18n/next 0.4.0 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-i18n/next",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Better-i18n Next.js integration",
   "license": "MIT",
   "repository": {
@@ -25,8 +25,8 @@
       "default": "./src/server.ts"
     },
     "./client": {
-      "types": "./src/client.ts",
-      "default": "./src/client.ts"
+      "types": "./src/client.tsx",
+      "default": "./src/client.tsx"
     },
     "./middleware": {
       "types": "./src/middleware.ts",
@@ -57,7 +57,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@better-i18n/core": "0.1.6"
+    "@better-i18n/core": "0.1.7"
   },
   "peerDependencies": {
     "next": ">=15.0.0",

package/src/client.tsx

@@ -0,0 +1,324 @@
+"use client";
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type ReactNode,
+} from "react";
+import { useRouter } from "next/navigation";
+import { NextIntlClientProvider } from "next-intl";
+import { createI18nCore, parseProject } from "@better-i18n/core";
+import type { LanguageOption, Messages } from "@better-i18n/core";
+
+import { normalizeConfig } from "./config";
+import type { I18nConfig } from "./types";
+
+// ─── BetterI18nProvider ──────────────────────────────────────────────
+
+interface BetterI18nContextValue {
+  setLocale: (locale: string) => void;
+}
+
+const BetterI18nContext = createContext<BetterI18nContextValue | null>(null);
+
+export interface BetterI18nProviderProps {
+  /** Initial locale from server (getLocale()) */
+  locale: string;
+  /** Initial messages from server (getMessages()) */
+  messages: Messages;
+  /** i18n config — only project and defaultLocale are required */
+  config: I18nConfig;
+  children: ReactNode;
+}
+
+/**
+ * Provider that wraps `NextIntlClientProvider` and enables instant locale
+ * switching without a server round-trip.
+ *
+ * When `useSetLocale()` is called inside this provider, it:
+ * 1. Sets a cookie (for server-side persistence on next navigation)
+ * 2. Fetches new messages from CDN on the client
+ * 3. Re-renders the tree with new locale + messages instantly
+ *
+ * @example
+ * ```tsx
+ * // app/layout.tsx
+ * import { BetterI18nProvider } from '@better-i18n/next/client'
+ *
+ * export default async function RootLayout({ children }) {
+ *   const locale = await getLocale()
+ *   const messages = await getMessages()
+ *
+ *   return (
+ *     <BetterI18nProvider
+ *       locale={locale}
+ *       messages={messages}
+ *       config={{ project: 'acme/dashboard', defaultLocale: 'en' }}
+ *     >
+ *       {children}
+ *     </BetterI18nProvider>
+ *   )
+ * }
+ * ```
+ */
+export function BetterI18nProvider({
+  locale: initialLocale,
+  messages: initialMessages,
+  config,
+  children,
+}: BetterI18nProviderProps) {
+  const normalized = useMemo(() => normalizeConfig(config), [
+    config.project,
+    config.defaultLocale,
+    config.cookieName,
+    config.cdnBaseUrl,
+  ]);
+
+  const [locale, setLocaleState] = useState(initialLocale);
+  const [messages, setMessages] = useState<Messages>(initialMessages);
+
+  // Sync with server-provided values when they change (e.g. navigation to a new page)
+  useEffect(() => {
+    setLocaleState(initialLocale);
+    setMessages(initialMessages);
+  }, [initialLocale, initialMessages]);
+
+  const setLocale = useCallback(
+    async (newLocale: string) => {
+      if (newLocale === locale) return;
+
+      // 1. Set cookie for server-side persistence
+      document.cookie = `${normalized.cookieName}=${newLocale}; path=/; max-age=31536000; samesite=lax`;
+
+      // 2. Fetch new messages from CDN
+      const { workspaceId, projectSlug } = parseProject(normalized.project);
+      const cdnBase = normalized.cdnBaseUrl || "https://cdn.better-i18n.com";
+      const url = `${cdnBase}/${workspaceId}/${projectSlug}/${newLocale}/translations.json`;
+
+      try {
+        const res = await fetch(url);
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        const newMessages: Messages = await res.json();
+
+        // 3. Instant client-side update — no server round-trip
+        setLocaleState(newLocale);
+        setMessages(newMessages);
+      } catch (err) {
+        console.error("[better-i18n] Client-side locale switch failed, falling back to refresh:", err);
+        // Fallback: let the server handle it
+        window.location.reload();
+      }
+    },
+    [locale, normalized]
+  );
+
+  return (
+    <BetterI18nContext.Provider value={{ setLocale }}>
+      <NextIntlClientProvider locale={locale} messages={messages}>
+        {children}
+      </NextIntlClientProvider>
+    </BetterI18nContext.Provider>
+  );
+}
+
+// ─── useManifestLanguages ────────────────────────────────────────────
+
+export type UseManifestLanguagesResult = {
+  languages: LanguageOption[];
+  isLoading: boolean;
+  error: Error | null;
+};
+
+type ClientCacheEntry = {
+  data?: LanguageOption[];
+  error?: Error;
+  promise?: Promise<LanguageOption[]>;
+};
+
+// Client-side request deduplication cache
+const clientCache = new Map<string, ClientCacheEntry>();
+
+const getCacheKey = (project: string, cdnBaseUrl?: string) =>
+  `${cdnBaseUrl || "https://cdn.better-i18n.com"}|${project}`;
+
+/**
+ * React hook to fetch manifest languages on the client
+ *
+ * Uses `createI18nCore` from `@better-i18n/core` internally with
+ * request deduplication to prevent duplicate fetches.
+ *
+ * @example
+ * ```tsx
+ * const { languages, isLoading, error } = useManifestLanguages({
+ *   project: 'acme/dashboard',
+ *   defaultLocale: 'en',
+ * })
+ *
+ * if (isLoading) return <Spinner />
+ * if (error) return <Error message={error.message} />
+ *
+ * return (
+ *   <select>
+ *     {languages.map(lang => (
+ *       <option key={lang.code} value={lang.code}>
+ *         {lang.nativeName || lang.name || lang.code}
+ *       </option>
+ *     ))}
+ *   </select>
+ * )
+ * ```
+ */
+export const useManifestLanguages = (config: I18nConfig): UseManifestLanguagesResult => {
+  const normalized = useMemo(
+    () => normalizeConfig(config),
+    [
+      config.project,
+      config.defaultLocale,
+      config.cdnBaseUrl,
+      config.debug,
+      config.logLevel,
+    ],
+  );
+
+  const i18nCore = useMemo(
+    () =>
+      createI18nCore({
+        project: normalized.project,
+        defaultLocale: normalized.defaultLocale,
+        cdnBaseUrl: normalized.cdnBaseUrl,
+        debug: normalized.debug,
+        logLevel: normalized.logLevel,
+      }),
+    [normalized],
+  );
+
+  const cacheKey = getCacheKey(normalized.project, normalized.cdnBaseUrl);
+  const cached = clientCache.get(cacheKey);
+
+  const [languages, setLanguages] = useState<LanguageOption[]>(cached?.data ?? []);
+  const [isLoading, setIsLoading] = useState(!cached?.data);
+  const [error, setError] = useState<Error | null>(cached?.error ?? null);
+
+  useEffect(() => {
+    let isMounted = true;
+
+    const run = async () => {
+      const entry = clientCache.get(cacheKey) ?? {};
+
+      // Return cached data if available
+      if (entry.data) {
+        if (isMounted) {
+          setLanguages(entry.data);
+          setIsLoading(false);
+        }
+        return;
+      }
+
+      // Deduplicate in-flight requests
+      if (!entry.promise) {
+        entry.promise = i18nCore
+          .getLanguages()
+          .then((langs) => {
+            clientCache.set(cacheKey, { data: langs });
+            return langs;
+          })
+          .catch((err) => {
+            const error = err instanceof Error ? err : new Error(String(err));
+            clientCache.set(cacheKey, { error });
+            throw error;
+          });
+        clientCache.set(cacheKey, entry);
+      }
+
+      try {
+        const langs = await entry.promise;
+        if (isMounted) {
+          setLanguages(langs);
+          setError(null);
+        }
+      } catch (err) {
+        if (isMounted) {
+          setError(err instanceof Error ? err : new Error(String(err)));
+        }
+      } finally {
+        if (isMounted) {
+          setIsLoading(false);
+        }
+      }
+    };
+
+    run();
+
+    return () => {
+      isMounted = false;
+    };
+  }, [cacheKey, i18nCore]);
+
+  return { languages, isLoading, error };
+};
+
+// ─── useSetLocale ────────────────────────────────────────────────────
+
+/**
+ * React hook that returns a function to switch the active locale.
+ *
+ * - **With `BetterI18nProvider`**: Fetches new messages client-side from CDN
+ *   and updates the UI instantly — no page refresh needed.
+ * - **Without provider (standalone)**: Pass a config object. Sets a cookie and
+ *   calls `router.refresh()` for a soft server re-render.
+ *
+ * @example With provider (recommended — instant switching)
+ * ```tsx
+ * // Wrap your layout with BetterI18nProvider, then:
+ * const setLocale = useSetLocale()
+ * <button onClick={() => setLocale('tr')}>Türkçe</button>
+ * ```
+ *
+ * @example Standalone (soft refresh)
+ * ```tsx
+ * const setLocale = useSetLocale({ project: 'acme/dashboard', defaultLocale: 'en' })
+ * <button onClick={() => setLocale('tr')}>Türkçe</button>
+ * ```
+ */
+export function useSetLocale(config?: I18nConfig): (locale: string) => void {
+  const ctx = useContext(BetterI18nContext);
+
+  // If BetterI18nProvider is in the tree, use instant client-side switching
+  if (ctx) {
+    return ctx.setLocale;
+  }
+
+  // Standalone fallback: cookie + router.refresh()
+  if (!config) {
+    throw new Error(
+      "[better-i18n] useSetLocale() requires either a <BetterI18nProvider> ancestor " +
+      "or a config argument. Use useSetLocale({ project, defaultLocale }) for standalone mode."
+    );
+  }
+
+  // eslint-disable-next-line react-hooks/rules-of-hooks
+  return useStandaloneSetLocale(config);
+}
+
+/** Internal standalone hook — cookie + router.refresh() */
+function useStandaloneSetLocale(config: I18nConfig) {
+  const normalized = useMemo(() => normalizeConfig(config), [
+    config.project,
+    config.defaultLocale,
+    config.cookieName,
+  ]);
+
+  const router = useRouter();
+
+  return useCallback(
+    (locale: string) => {
+      document.cookie = `${normalized.cookieName}=${locale}; path=/; max-age=31536000; samesite=lax`;
+      router.refresh();
+    },
+    [normalized.cookieName, router]
+  );
+}

package/src/config.ts

@@ -27,6 +27,7 @@ export const normalizeConfig = (config: I18nConfig): NormalizedConfig => {
   return {
     ...coreConfig,
     localePrefix: config.localePrefix ?? "as-needed",
+    cookieName: config.cookieName ?? "locale",
     manifestRevalidateSeconds: config.manifestRevalidateSeconds ?? 3600,
     messagesRevalidateSeconds: config.messagesRevalidateSeconds ?? 30,
   };

package/src/index.ts

@@ -81,6 +81,7 @@ export const createI18n = (config: I18nConfig) => {
           detection: {
             cookie: true,
             browserLanguage: true,
+            cookieName: normalized.cookieName,
           },
         },
         callback
@@ -96,8 +97,9 @@ export type { MiddlewareContext, MiddlewareCallback } from "./middleware";
 // Core instance factory
 export { createNextI18nCore } from "./server";
 
-// Client hook
-export { useManifestLanguages } from "./client";
+// Client hooks & provider
+export { BetterI18nProvider, useManifestLanguages, useSetLocale } from "./client";
+export type { BetterI18nProviderProps } from "./client";
 
 // Re-export types
 export type {

package/src/middleware.ts

@@ -107,19 +107,12 @@ export function createBetterI18nMiddleware(
     // 1. Fetch available locales from CDN
     const availableLocales = await i18nCore.getLocales();
 
-    // 2. Create/reuse next-intl middleware (only recreate if locales changed)
-    const localesKey = availableLocales.join(",");
-    if (!cachedMiddleware || cachedLocalesKey !== localesKey) {
-      cachedMiddleware = createMiddleware({
-        locales: availableLocales,
-        defaultLocale,
-        localePrefix,
-      });
-      cachedLocalesKey = localesKey;
-    }
-
-    // 3. Our custom locale detection (for cookie logic)
-    const pathLocale = request.nextUrl.pathname.split("/")[1];
+    // 2. Our custom locale detection
+    // When localePrefix is "never", path has no locale segment — skip it
+    const pathLocale =
+      localePrefix === "never"
+        ? null
+        : request.nextUrl.pathname.split("/")[1];
     const cookieLocale = cookie ? request.cookies.get(cookieName)?.value : null;
     const headerLocale = browserLanguage
       ? request.headers.get("accept-language")?.split(",")[0]?.split("-")[0]
@@ -134,18 +127,37 @@ export function createBetterI18nMiddleware(
       availableLocales,
     });
 
-    // 4. Call next-intl middleware (sets x-middleware-request-x-next-intl-locale header)
-    const response = cachedMiddleware(request);
-
-    // 5. Get detected locale from next-intl header (more accurate than our detection)
-    const detectedLocale =
-      response.headers.get("x-middleware-request-x-next-intl-locale") ||
-      result.locale;
+    const detectedLocale = result.locale;
+
+    let response: NextResponse;
+
+    if (localePrefix === "never") {
+      // 3a. "never" mode: bypass next-intl middleware entirely.
+      // next-intl's createMiddleware tries URL rewriting which breaks cookie-only locale.
+      // We create a plain response and set the header that next-intl's getRequestConfig reads.
+      response = NextResponse.next();
+      response.headers.set(
+        "x-middleware-request-x-next-intl-locale",
+        detectedLocale
+      );
+    } else {
+      // 3b. URL-based modes: delegate to next-intl middleware as before
+      const localesKey = availableLocales.join(",");
+      if (!cachedMiddleware || cachedLocalesKey !== localesKey) {
+        cachedMiddleware = createMiddleware({
+          locales: availableLocales,
+          defaultLocale,
+          localePrefix,
+        });
+        cachedLocalesKey = localesKey;
+      }
+      response = cachedMiddleware(request);
+    }
 
-    // 6. Add x-locale header for backwards compatibility
+    // 4. Add x-locale header for backwards compatibility
     response.headers.set("x-locale", detectedLocale);
 
-    // 7. Set our custom cookie if needed
+    // 5. Set our custom cookie if needed
     if (cookie && result.shouldSetCookie) {
       response.cookies.set(cookieName, detectedLocale, {
         path: "/",
@@ -154,7 +166,7 @@ export function createBetterI18nMiddleware(
       });
     }
 
-    // 8. If callback provided, execute it (Clerk-style)
+    // 6. If callback provided, execute it (Clerk-style)
     if (callback) {
       const callbackResult = await callback(request, {
         locale: detectedLocale,
@@ -167,7 +179,7 @@ export function createBetterI18nMiddleware(
       }
     }
 
-    // 9. Return the i18n response (with all headers preserved)
+    // 7. Return the response
     return response;
   };
 }

package/src/server.ts

@@ -1,4 +1,5 @@
 import { getRequestConfig } from "next-intl/server";
+import { cookies } from "next/headers";
 import { createI18nCore } from "@better-i18n/core";
 import type { I18nCore, Messages } from "@better-i18n/core";
 
@@ -98,8 +99,25 @@ export const createNextIntlRequestConfig = (config: I18nConfig) =>
     const i18n = createNextI18nCore(config);
     const normalized = normalizeConfig(config);
     const locales = await i18n.getLocales();
+
+    // 1. Middleware header (set by next-intl or our middleware)
     let locale = await requestLocale;
 
+    // 2. Cookie fallback — critical for localePrefix: "never" where
+    //    requestLocale may be undefined if middleware header isn't forwarded
+    if (!locale) {
+      try {
+        const cookieStore = await cookies();
+        const cookieLocale = cookieStore.get(normalized.cookieName)?.value;
+        if (cookieLocale && locales.includes(cookieLocale)) {
+          locale = cookieLocale;
+        }
+      } catch {
+        // cookies() throws in non-request contexts (e.g. build time)
+      }
+    }
+
+    // 3. Final fallback to defaultLocale
     if (!locale || !locales.includes(locale)) {
       locale = normalized.defaultLocale;
     }

package/src/types.ts

@@ -27,6 +27,12 @@ export interface I18nConfig extends I18nCoreConfig {
    */
   localePrefix?: LocalePrefix;
 
+  /**
+   * Cookie name used for locale persistence when localePrefix is "never"
+   * @default "locale"
+   */
+  cookieName?: string;
+
   /**
    * Next.js ISR revalidation time for manifest (seconds)
    * @default 3600
@@ -45,6 +51,7 @@ export interface I18nConfig extends I18nCoreConfig {
  */
 export interface NormalizedConfig extends CoreNormalizedConfig, Omit<I18nConfig, keyof I18nCoreConfig> {
   localePrefix: LocalePrefix;
+  cookieName: string;
   manifestRevalidateSeconds: number;
   messagesRevalidateSeconds: number;
 }

package/src/client.ts

@@ -1,142 +0,0 @@
-"use client";
-
-import { useEffect, useMemo, useState } from "react";
-import { createI18nCore } from "@better-i18n/core";
-import type { LanguageOption } from "@better-i18n/core";
-
-import { normalizeConfig } from "./config";
-import type { I18nConfig } from "./types";
-
-export type UseManifestLanguagesResult = {
-  languages: LanguageOption[];
-  isLoading: boolean;
-  error: Error | null;
-};
-
-type ClientCacheEntry = {
-  data?: LanguageOption[];
-  error?: Error;
-  promise?: Promise<LanguageOption[]>;
-};
-
-// Client-side request deduplication cache
-const clientCache = new Map<string, ClientCacheEntry>();
-
-const getCacheKey = (project: string, cdnBaseUrl?: string) =>
-  `${cdnBaseUrl || "https://cdn.better-i18n.com"}|${project}`;
-
-/**
- * React hook to fetch manifest languages on the client
- *
- * Uses `createI18nCore` from `@better-i18n/core` internally with
- * request deduplication to prevent duplicate fetches.
- *
- * @example
- * ```tsx
- * const { languages, isLoading, error } = useManifestLanguages({
- *   project: 'acme/dashboard',
- *   defaultLocale: 'en',
- * })
- *
- * if (isLoading) return <Spinner />
- * if (error) return <Error message={error.message} />
- *
- * return (
- *   <select>
- *     {languages.map(lang => (
- *       <option key={lang.code} value={lang.code}>
- *         {lang.nativeName || lang.name || lang.code}
- *       </option>
- *     ))}
- *   </select>
- * )
- * ```
- */
-export const useManifestLanguages = (config: I18nConfig): UseManifestLanguagesResult => {
-  const normalized = useMemo(
-    () => normalizeConfig(config),
-    [
-      config.project,
-      config.defaultLocale,
-      config.cdnBaseUrl,
-      config.debug,
-      config.logLevel,
-    ],
-  );
-
-  const i18nCore = useMemo(
-    () =>
-      createI18nCore({
-        project: normalized.project,
-        defaultLocale: normalized.defaultLocale,
-        cdnBaseUrl: normalized.cdnBaseUrl,
-        debug: normalized.debug,
-        logLevel: normalized.logLevel,
-      }),
-    [normalized],
-  );
-
-  const cacheKey = getCacheKey(normalized.project, normalized.cdnBaseUrl);
-  const cached = clientCache.get(cacheKey);
-
-  const [languages, setLanguages] = useState<LanguageOption[]>(cached?.data ?? []);
-  const [isLoading, setIsLoading] = useState(!cached?.data);
-  const [error, setError] = useState<Error | null>(cached?.error ?? null);
-
-  useEffect(() => {
-    let isMounted = true;
-
-    const run = async () => {
-      const entry = clientCache.get(cacheKey) ?? {};
-
-      // Return cached data if available
-      if (entry.data) {
-        if (isMounted) {
-          setLanguages(entry.data);
-          setIsLoading(false);
-        }
-        return;
-      }
-
-      // Deduplicate in-flight requests
-      if (!entry.promise) {
-        entry.promise = i18nCore
-          .getLanguages()
-          .then((langs) => {
-            clientCache.set(cacheKey, { data: langs });
-            return langs;
-          })
-          .catch((err) => {
-            const error = err instanceof Error ? err : new Error(String(err));
-            clientCache.set(cacheKey, { error });
-            throw error;
-          });
-        clientCache.set(cacheKey, entry);
-      }
-
-      try {
-        const langs = await entry.promise;
-        if (isMounted) {
-          setLanguages(langs);
-          setError(null);
-        }
-      } catch (err) {
-        if (isMounted) {
-          setError(err instanceof Error ? err : new Error(String(err)));
-        }
-      } finally {
-        if (isMounted) {
-          setIsLoading(false);
-        }
-      }
-    };
-
-    run();
-
-    return () => {
-      isMounted = false;
-    };
-  }, [cacheKey, i18nCore]);
-
-  return { languages, isLoading, error };
-};