@better-i18n/use-intl 0.1.8 → 0.2.0

package/src/hooks/useLocaleRouter.ts

@@ -1,147 +0,0 @@
-"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/index.ts

@@ -1,46 +0,0 @@
-// Provider
-export { BetterI18nProvider } from "./provider";
-export type { BetterI18nProviderProps } from "./provider";
-
-// Context & Hooks
-export { useBetterI18n } from "./context";
-export {
-  useLanguages,
-  useLocale,
-  // Re-exported from use-intl
-  useTranslations,
-  useFormatter,
-  useMessages,
-  useNow,
-  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";
-
-// Types
-export type {
-  Messages,
-  BetterI18nProviderConfig,
-  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,114 +0,0 @@
-// @ts-expect-error - internal workspace dependency
-import { createMiddleware } from "@tanstack/react-router";
-// @ts-expect-error - internal workspace dependency
-import { detectLocale, getLocales } from "@better-i18n/core";
-import type { I18nMiddlewareConfig } from "@better-i18n/core";
-
-export function createBetterI18nMiddleware(config: I18nMiddlewareConfig) {
-  const { project, defaultLocale, localePrefix = "as-needed", detection = {} } = config;
-
-  const {
-    cookie = true,
-    browserLanguage = true,
-    cookieName = "locale",
-    cookieMaxAge = 31536000,
-  } = detection;
-
-  return createMiddleware().server(
-    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 pathSegment = url.pathname.split("/")[1];
-      const hasLocaleInPath =
-        !!pathSegment && availableLocales.includes(pathSegment);
-
-      // Dynamic imports for TanStack Start server functions to avoid bundling them in client
-      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
-        ? getRequestHeader("accept-language")?.split(",")[0]?.split("-")[0]
-        : null;
-
-      // 3. Detect locale using core logic
-      const result = detectLocale({
-        project,
-        defaultLocale,
-        pathLocale: pathSegment,
-        cookieLocale,
-        headerLocale,
-        availableLocales,
-      });
-
-      // 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: "/",
-          maxAge: cookieMaxAge,
-          sameSite: "lax",
-        });
-      }
-
-      // 6. Pass locale to route context
-      return next({ context: { locale: result.locale } });
-    },
-  );
-}

package/src/provider.tsx

@@ -1,183 +0,0 @@
-"use client";
-
-import { createI18nCore } from "@better-i18n/core";
-import type { LanguageOption } from "@better-i18n/core";
-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";
-
-export interface BetterI18nProviderProps extends BetterI18nProviderConfig {
-  children: ReactNode;
-}
-
-/**
- * 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)
- * function App() {
- *   return (
- *     <BetterI18nProvider
- *       project="acme/dashboard"
- *       locale="en"
- *     >
- *       <MyComponent />
- *     </BetterI18nProvider>
- *   )
- * }
- *
- * // 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}
- *     >
- *       <Outlet />
- *     </BetterI18nProvider>
- *   )
- * }
- * ```
- */
-export function BetterI18nProvider({
-  children,
-  project,
-  locale: propLocale,
-  messages: propMessages,
-  timeZone,
-  now,
-  onError,
-  cdnBaseUrl,
-  debug,
-  logLevel,
-  fetch: customFetch,
-}: BetterI18nProviderProps) {
-  // 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(!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: locale,
-        cdnBaseUrl,
-        debug,
-        logLevel,
-        fetch: customFetch,
-      }),
-    [project, locale, cdnBaseUrl, debug, logLevel, customFetch]
-  );
-
-  // Load languages on mount
-  useEffect(() => {
-    let cancelled = false;
-
-    const loadLanguages = async () => {
-      try {
-        const langs = await i18nCore.getLanguages();
-        if (!cancelled) {
-          setLanguages(langs);
-        }
-      } catch (error) {
-        console.error("[better-i18n] Failed to load languages:", error);
-      } finally {
-        if (!cancelled) {
-          setIsLoadingLanguages(false);
-        }
-      }
-    };
-
-    loadLanguages();
-
-    return () => {
-      cancelled = true;
-    };
-  }, [i18nCore]);
-
-  // Load messages when locale changes and no pre-loaded messages available
-  useEffect(() => {
-    // Skip if we already have messages for this render
-    if (propMessages) {
-      return;
-    }
-
-    let cancelled = false;
-
-    const loadMessages = async () => {
-      setIsLoadingMessages(true);
-
-      try {
-        const msgs = await i18nCore.getMessages(locale);
-        if (!cancelled) {
-          setMessages(msgs as Messages);
-        }
-      } catch (error) {
-        console.error(
-          `[better-i18n] Failed to load messages for locale "${locale}":`,
-          error
-        );
-      } finally {
-        if (!cancelled) {
-          setIsLoadingMessages(false);
-        }
-      }
-    };
-
-    loadMessages();
-
-    return () => {
-      cancelled = true;
-    };
-  }, [locale, i18nCore, propMessages]);
-
-  // Context value (read-only locale - use useLocaleRouter for navigation)
-  const contextValue = useMemo(
-    () => ({
-      locale,
-      languages,
-      isLoadingLanguages,
-      isLoadingMessages,
-      project,
-    }),
-    [locale, languages, isLoadingLanguages, isLoadingMessages, project]
-  );
-
-  // Don't render until we have messages
-  if (!messages) {
-    return null;
-  }
-
-  return (
-    <BetterI18nContext.Provider value={contextValue}>
-      <IntlProvider
-        locale={locale}
-        messages={messages}
-        timeZone={timeZone}
-        now={now}
-        onError={onError}
-      >
-        {children}
-      </IntlProvider>
-    </BetterI18nContext.Provider>
-  );
-}

package/src/server.ts

@@ -1,108 +0,0 @@
-import { createI18nCore } from "@better-i18n/core";
-import type { I18nCoreConfig, LanguageOption } from "@better-i18n/core";
-import { createFormatter, createTranslator } from "use-intl/core";
-import type { Messages } from "./types.js";
-
-export interface GetMessagesConfig extends Omit<
-  I18nCoreConfig,
-  "defaultLocale"
-> {
-  /**
-   * Locale to fetch messages for
-   */
-  locale: string;
-}
-
-/**
- * Fetch messages for a locale (server-side)
- */
-export async function getMessages(
-  config: GetMessagesConfig,
-): Promise<Messages> {
-  const i18n = createI18nCore({
-    project: config.project,
-    defaultLocale: config.locale,
-    cdnBaseUrl: config.cdnBaseUrl,
-    debug: config.debug,
-    logLevel: config.logLevel,
-    fetch: config.fetch,
-  });
-
-  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
-  // if it's deeply nested, use-intl also handles nested objects.
-
-  return messages as Messages;
-}
-
-/**
- * Fetch available locales (server-side)
- */
-export async function getLocales(
-  config: Omit<I18nCoreConfig, "defaultLocale"> & { defaultLocale?: string },
-): Promise<string[]> {
-  const i18n = createI18nCore({
-    project: config.project,
-    defaultLocale: config.defaultLocale || "en",
-    cdnBaseUrl: config.cdnBaseUrl,
-    debug: config.debug,
-    logLevel: config.logLevel,
-    fetch: config.fetch,
-  });
-
-  return i18n.getLocales();
-}
-
-/**
- * Fetch available languages with metadata (server-side)
- */
-export async function getLanguages(
-  config: Omit<I18nCoreConfig, "defaultLocale"> & { defaultLocale?: string },
-): Promise<LanguageOption[]> {
-  const i18n = createI18nCore({
-    project: config.project,
-    defaultLocale: config.defaultLocale || "en",
-    cdnBaseUrl: config.cdnBaseUrl,
-    debug: config.debug,
-    logLevel: config.logLevel,
-    fetch: config.fetch,
-  });
-
-  return i18n.getLanguages();
-}
-
-/**
- * Create a translator function for use outside React (server-side)
- */
-export function createServerTranslator(config: {
-  locale: string;
-  messages: Messages;
-  namespace?: string;
-}) {
-  return createTranslator({
-    locale: config.locale,
-    messages: config.messages as Parameters<
-      typeof createTranslator
-    >[0]["messages"],
-    namespace: config.namespace,
-  });
-}
-
-/**
- * Create a formatter for use outside React (server-side)
- */
-export function createServerFormatter(config: {
-  locale: string;
-  timeZone?: string;
-  now?: Date;
-}) {
-  return createFormatter({
-    locale: config.locale,
-    timeZone: config.timeZone,
-    now: config.now,
-  });
-}
-
-export { createTranslator, createFormatter } from "use-intl/core";

package/src/types.ts

@@ -1,83 +0,0 @@
-import type { I18nCoreConfig, LanguageOption } from "@better-i18n/core";
-import type { ComponentProps } from "react";
-import type { IntlProvider } from "use-intl";
-
-/**
- * Messages type (compatible with use-intl)
- */
-export type Messages = ComponentProps<typeof IntlProvider>["messages"];
-
-/**
- * Configuration for BetterI18nProvider
- */
-export interface BetterI18nProviderConfig
-  extends Omit<I18nCoreConfig, "defaultLocale"> {
-  /**
-   * Current locale
-   */
-  locale: string;
-
-  /**
-   * Pre-loaded messages (for SSR hydration)
-   */
-  messages?: Messages;
-
-  /**
-   * Timezone for date/time formatting
-   * @default undefined (uses browser timezone)
-   */
-  timeZone?: string;
-
-  /**
-   * Current date/time (useful for SSR to prevent hydration mismatches)
-   */
-  now?: Date;
-
-  /**
-   * Error handler for missing translations
-   */
-  onError?: ComponentProps<typeof IntlProvider>["onError"];
-}
-
-/**
- * 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 (read-only - use useLocaleRouter().navigate() to change)
-   */
-  locale: string;
-
-  /**
-   * Available languages with metadata from CDN manifest
-   */
-  languages: LanguageOption[];
-
-  /**
-   * Whether languages are still loading from CDN
-   */
-  isLoadingLanguages: boolean;
-
-  /**
-   * Whether messages are still loading
-   */
-  isLoadingMessages: boolean;
-
-  /**
-   * Project identifier
-   */
-  project: string;
-}
-
-/**
- * Server-side configuration for getMessages
- */
-export interface GetMessagesConfig extends I18nCoreConfig {
-  /**
-   * Locale to fetch messages for
-   */
-  locale: string;
-}