@better-i18n/use-intl 0.1.3 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-i18n/use-intl",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Better i18n integration for use-intl (React, TanStack Start)",
   "license": "MIT",
   "repository": {
@@ -22,7 +22,7 @@
     "./package.json": "./package.json"
   },
   "files": [
-    "dist",
+    "src",
     "package.json",
     "README.md"
   ],
@@ -44,7 +44,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@better-i18n/core": "0.1.3"
+    "@better-i18n/core": "0.1.4"
   },
   "peerDependencies": {
     "react": ">=18.0.0",

package/src/components.tsx

@@ -0,0 +1,76 @@
+"use client";
+
+import type { ComponentProps, ReactNode } from "react";
+import { useBetterI18n } from "./context";
+
+export interface LanguageSwitcherProps extends Omit<
+  ComponentProps<"select">,
+  "value" | "onChange" | "children"
+> {
+  /**
+   * Render function for custom option display
+   */
+  renderOption?: (language: {
+    code: string;
+    name?: string;
+    nativeName?: string;
+    flagUrl?: string | null;
+  }) => ReactNode;
+
+  /**
+   * Label for loading state
+   */
+  loadingLabel?: string;
+}
+
+/**
+ * Pre-built language switcher component
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <LanguageSwitcher />
+ *
+ * // With custom styling
+ * <LanguageSwitcher className="my-select" />
+ *
+ * // Custom option rendering
+ * <LanguageSwitcher
+ *   renderOption={(lang) => (
+ *     <>
+ *       {lang.flagUrl && <img src={lang.flagUrl} alt="" />}
+ *       {lang.nativeName}
+ *     </>
+ *   )}
+ * />
+ * ```
+ */
+export function LanguageSwitcher({
+  renderOption,
+  loadingLabel = "Loading...",
+  ...props
+}: LanguageSwitcherProps) {
+  const { locale, setLocale, languages, isLoadingLanguages } = useBetterI18n();
+
+  if (isLoadingLanguages) {
+    return (
+      <select disabled {...props}>
+        <option>{loadingLabel}</option>
+      </select>
+    );
+  }
+
+  return (
+    <select
+      value={locale}
+      onChange={(e) => setLocale(e.target.value)}
+      {...props}
+    >
+      {languages.map((lang) => (
+        <option key={lang.code} value={lang.code}>
+          {renderOption ? renderOption(lang) : lang.nativeName || lang.code}
+        </option>
+      ))}
+    </select>
+  );
+}

package/src/context.tsx

@@ -0,0 +1,43 @@
+"use client";
+
+import { createContext, useContext } from "react";
+import type { BetterI18nContextValue } from "./types";
+
+/**
+ * Context for Better i18n specific state
+ */
+export const BetterI18nContext = createContext<BetterI18nContextValue | null>(
+  null
+);
+
+/**
+ * Hook to access Better i18n context
+ *
+ * @example
+ * ```tsx
+ * function LanguageSwitcher() {
+ *   const { locale, setLocale, languages } = useBetterI18n()
+ *
+ *   return (
+ *     <select value={locale} onChange={(e) => setLocale(e.target.value)}>
+ *       {languages.map((lang) => (
+ *         <option key={lang.code} value={lang.code}>
+ *           {lang.nativeName}
+ *         </option>
+ *       ))}
+ *     </select>
+ *   )
+ * }
+ * ```
+ */
+export function useBetterI18n(): BetterI18nContextValue {
+  const context = useContext(BetterI18nContext);
+
+  if (!context) {
+    throw new Error(
+      "[better-i18n] useBetterI18n must be used within a BetterI18nProvider"
+    );
+  }
+
+  return context;
+}

package/src/hooks.ts

@@ -0,0 +1,70 @@
+"use client";
+
+import { useBetterI18n } from "./context";
+
+/**
+ * Hook to get available languages
+ *
+ * @example
+ * ```tsx
+ * function LanguageList() {
+ *   const { languages, isLoading } = useLanguages()
+ *
+ *   if (isLoading) return <div>Loading...</div>
+ *
+ *   return (
+ *     <ul>
+ *       {languages.map((lang) => (
+ *         <li key={lang.code}>
+ *           {lang.nativeName} ({lang.code})
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   )
+ * }
+ * ```
+ */
+export function useLanguages() {
+  const { languages, isLoadingLanguages } = useBetterI18n();
+
+  return {
+    languages,
+    isLoading: isLoadingLanguages,
+  };
+}
+
+/**
+ * Hook to get and set current locale
+ *
+ * @example
+ * ```tsx
+ * function LocaleSwitcher() {
+ *   const { locale, setLocale } = useLocale()
+ *
+ *   return (
+ *     <button onClick={() => setLocale(locale === 'en' ? 'tr' : 'en')}>
+ *       Current: {locale}
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
+export function useLocale() {
+  const { locale, setLocale, isLoadingMessages } = useBetterI18n();
+
+  return {
+    locale,
+    setLocale,
+    isLoading: isLoadingMessages,
+  };
+}
+
+// Re-export use-intl hooks for convenience
+export {
+  useTranslations,
+  useFormatter,
+  useMessages,
+  useNow,
+  useTimeZone,
+  useLocale as useIntlLocale,
+} from "use-intl";

package/src/index.ts

@@ -0,0 +1,30 @@
+// 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";
+
+// Components
+export { LanguageSwitcher } from "./components";
+export type { LanguageSwitcherProps } from "./components";
+
+// Types
+export type {
+  Messages,
+  BetterI18nProviderConfig,
+  BetterI18nContextValue,
+} from "./types";
+
+// Re-export commonly used use-intl components
+export { IntlProvider } from "use-intl";

package/src/middleware/index.ts

@@ -0,0 +1,61 @@
+// @ts-ignore - internal workspace dependency
+import { createMiddleware } from "@tanstack/react-router";
+// @ts-ignore - 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 {
+    cookie = true,
+    browserLanguage = true,
+    cookieName = "locale",
+    cookieMaxAge = 31536000,
+  } = detection;
+
+  return createMiddleware().server(
+    async ({ next, request }: { next: any; request: any }) => {
+      // 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];
+
+      // 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 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,
+        cookieLocale,
+        headerLocale,
+        availableLocales,
+      });
+
+      // 4. Set cookie if needed (if enabled and changed)
+      if (cookie && result.shouldSetCookie) {
+        setCookie(cookieName, result.locale, {
+          path: "/",
+          maxAge: cookieMaxAge,
+          sameSite: "lax",
+        });
+      }
+
+      // 5. Pass locale to route context
+      return next({ context: { locale: result.locale } });
+    },
+  );
+}

package/src/provider.tsx

@@ -0,0 +1,196 @@
+"use client";
+
+import { createI18nCore } from "@better-i18n/core";
+import type { LanguageOption } from "@better-i18n/core";
+import {
+  useCallback,
+  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
+ *
+ * @example
+ * ```tsx
+ * // Basic usage (CSR - fetches messages on client)
+ * function App() {
+ *   return (
+ *     <BetterI18nProvider
+ *       project="acme/dashboard"
+ *       locale="en"
+ *     >
+ *       <MyComponent />
+ *     </BetterI18nProvider>
+ *   )
+ * }
+ *
+ * // SSR usage (pre-loaded messages)
+ * function App({ locale, messages }) {
+ *   return (
+ *     <BetterI18nProvider
+ *       project="acme/dashboard"
+ *       locale={locale}
+ *       messages={messages}
+ *     >
+ *       <MyComponent />
+ *     </BetterI18nProvider>
+ *   )
+ * }
+ * ```
+ */
+export function BetterI18nProvider({
+  children,
+  project,
+  locale: initialLocale,
+  messages: initialMessages,
+  timeZone,
+  now,
+  onLocaleChange,
+  onError,
+  cdnBaseUrl,
+  debug,
+  logLevel,
+  fetch: customFetch,
+}: BetterI18nProviderProps) {
+  const [locale, setLocaleState] = useState(initialLocale);
+  const [messages, setMessages] = useState<Messages | undefined>(
+    initialMessages,
+  );
+  const [languages, setLanguages] = useState<LanguageOption[]>([]);
+  const [isLoadingMessages, setIsLoadingMessages] = useState(!initialMessages);
+  const [isLoadingLanguages, setIsLoadingLanguages] = useState(true);
+
+  // Create i18n core instance
+  const i18nCore = useMemo(
+    () =>
+      createI18nCore({
+        project,
+        defaultLocale: initialLocale,
+        cdnBaseUrl,
+        debug,
+        logLevel,
+        fetch: customFetch,
+      }),
+    [project, initialLocale, 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 (if not pre-loaded)
+  useEffect(() => {
+    // Skip if we have initial messages for the current locale
+    if (initialMessages && locale === initialLocale) {
+      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, initialMessages, initialLocale]);
+
+  // Locale change handler
+  const setLocale = useCallback(
+    (newLocale: string) => {
+      setLocaleState(newLocale);
+      onLocaleChange?.(newLocale);
+    },
+    [onLocaleChange],
+  );
+
+  // Context value
+  const contextValue = useMemo(
+    () => ({
+      locale,
+      setLocale,
+      languages,
+      isLoadingLanguages,
+      isLoadingMessages,
+      project,
+    }),
+    [
+      locale,
+      setLocale,
+      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

@@ -0,0 +1,108 @@
+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 any;
+
+  // 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

@@ -0,0 +1,90 @@
+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;
+
+  /**
+   * Callback when locale changes
+   */
+  onLocaleChange?: (locale: string) => void;
+
+  /**
+   * Error handler for missing translations
+   */
+  onError?: ComponentProps<typeof IntlProvider>["onError"];
+}
+
+/**
+ * Better i18n context value
+ */
+export interface BetterI18nContextValue {
+  /**
+   * Current locale
+   */
+  locale: string;
+
+  /**
+   * Change the current locale
+   */
+  setLocale: (locale: string) => void;
+
+  /**
+   * Available languages with metadata
+   */
+  languages: LanguageOption[];
+
+  /**
+   * Whether languages are still loading
+   */
+  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;
+}