Next.js API Reference

import { createBetterI18nMiddleware } from "@better-i18n/next";
import { NextResponse } from "next/server";

// Simple usage (no callback)
export default createBetterI18nMiddleware({
  projectId: "org/project",
  defaultLocale: "en",
  localePrefix: "always",
});

// With callback (recommended for auth)
export default createBetterI18nMiddleware({
  projectId: "org/project",
  defaultLocale: "en",
  localePrefix: "always",
}, async (request, { locale, response }) => {
  // Auth logic here - locale is available!
  if (needsLogin) {
    return NextResponse.redirect(new URL(`/${locale}/login`, request.url));
  }
  // Return nothing = i18n response is used (headers preserved!)
});

// ❌ Deprecated - headers can be lost
import { createBetterI18nMiddleware, composeMiddleware } from "@better-i18n/next";

const i18n = createBetterI18nMiddleware(config);
const auth = authMiddleware;

export default composeMiddleware(i18n, auth);

// ✅ Recommended - use callback pattern instead
export default createBetterI18nMiddleware(config, async (req, { locale }) => {
  // Auth logic here
});

import { createI18n } from "@better-i18n/next";

const i18n = createI18n({
  projectId: "org/project",
  defaultLocale: "en",
  // Optional
  localePrefix: "as-needed", // "as-needed" | "always" | "never"
  manifestRevalidateSeconds: 3600, // ISR for manifest
  messagesRevalidateSeconds: 30, // ISR for messages
  debug: false,
});

// src/i18n/request.ts
export default i18n.requestConfig;

// middleware.ts - Simple usage
export default i18n.betterMiddleware();

// middleware.ts - With auth callback
export default i18n.betterMiddleware(async (request, { locale, response }) => {
  if (needsLogin) {
    return NextResponse.redirect(new URL(`/${locale}/login`, request.url));
  }
  // Return nothing = i18n response is used (headers preserved!)
});

// middleware.ts
export default i18n.middleware;

const manifest = await i18n.getManifest();

// Force refresh (bypass cache)
const manifest = await i18n.getManifest({ forceRefresh: true });

// Full fetch (all namespaces)
const messages = await i18n.getMessages("tr");
// { common: { welcome: "Hoş geldiniz" }, ... }

// Selective — only fetch these namespaces (namespaced_folders projects)
const subset = await i18n.getMessages("tr", {
  namespaces: ["common", "hero"],
});

const locales = await i18n.getLocales();
// ["en", "tr", "de", "fr"]

import { createNextI18nCore } from "@better-i18n/next";

const i18nCore = createNextI18nCore({
  projectId: "org/project",
  defaultLocale: "en",
  manifestRevalidateSeconds: 3600,
  messagesRevalidateSeconds: 30,
});

// All core methods available
const manifest = await i18nCore.getManifest();
const messages = await i18nCore.getMessages("en");
const locales = await i18nCore.getLocales();
const languages = await i18nCore.getLanguages();

import {
  createNextIntlRequestConfig,
  getManifest,
  getMessages,
  getLocales,
  getManifestLanguages,
} from "@better-i18n/next/server";

// src/i18n/request.ts
import { createNextIntlRequestConfig } from "@better-i18n/next/server";

export default createNextIntlRequestConfig({
  projectId: "org/project",
  defaultLocale: "en",
});

import { getMessages } from "@better-i18n/next/server";

// Full fetch
const messages = await getMessages(
  { projectId: "org/project", defaultLocale: "en" },
  "tr"
);

// Selective — only fetch these namespaces
const subset = await getMessages(
  { projectId: "org/project", defaultLocale: "en" },
  "tr",
  { namespaces: ["common", "pricing"] }
);

import { getLocales } from "@better-i18n/next/server";

const locales = await getLocales({
  projectId: "org/project",
  defaultLocale: "en",
});

import { getManifestLanguages } from "@better-i18n/next/server";

const languages = await getManifestLanguages({
  projectId: "org/project",
  defaultLocale: "en",
});
// [{ code: "tr", name: "Turkish", nativeName: "Türkçe", flagUrl: "..." }]

import {
  BetterI18nProvider,
  useSetLocale,
  useManifestLanguages,
} from "@better-i18n/next/client";

import { BetterI18nProvider } from '@better-i18n/next/client';

// In your Root Layout:
<BetterI18nProvider config={i18n.config} locale={locale} messages={messages}>
  {children}
</BetterI18nProvider>

// With BetterI18nProvider in tree → instant CDN fetch + re-render
const setLocale = useSetLocale();
setLocale('tr');

// Without provider → cookie update + router.refresh()
const setLocale = useSetLocale({ config: i18n.config });
setLocale('tr');

"use client";

import { useManifestLanguages } from "@better-i18n/next/client";

function LanguageSwitcher() {
  const { languages, isLoading, error } = useManifestLanguages({
    projectId: "org/project",
    defaultLocale: "en",
  });

  if (isLoading) return <span>Loading...</span>;
  if (error) return <span>Error: {error.message}</span>;

  return (
    <select>
      {languages.map((lang) => (
        <option key={lang.code} value={lang.code}>
          {lang.nativeName || lang.name || lang.code}
        </option>
      ))}
    </select>
  );
}

interface I18nConfig {
  // Required
  projectId: string; // "org/project" slug or canonical UUID
  defaultLocale: string; // Fallback locale

  // Optional - CDN
  cdnBaseUrl?: string; // Default: "https://cdn.better-i18n.com"

  // Optional - Next.js ISR
  manifestRevalidateSeconds?: number; // Default: 3600 (1 hour)
  messagesRevalidateSeconds?: number; // Default: 30

  // Optional - Routing
  localePrefix?: "as-needed" | "always" | "never"; // Default: "as-needed"

  // Optional - Locale persistence
  cookieName?: string; // Default: "locale"
  explicitCookieName?: string; // Default: `${cookieName}_explicit` — marks a deliberate user choice

  // Optional - Timezone
  timeZone?: string; // IANA timezone (set explicitly to avoid ENVIRONMENT_FALLBACK warnings)

  // Optional - Offline support
  storage?: TranslationStorage; // Persistent storage adapter
  staticData?: Record<string, Messages> | (() => Promise<Record<string, Messages>>); // Last-resort bundled translations

  // Optional - Resilience
  fetchTimeout?: number; // Default: 10000 (ms)
  retryCount?: number; // Default: 1

  // Optional - Debugging
  debug?: boolean; // Enable debug logging
  logLevel?: "debug" | "info" | "warn" | "error" | "silent";
}

interface I18nMiddlewareConfig {
  projectId: string;
  defaultLocale: string;
  /** URL locale prefix behavior (passed to next-intl) */
  localePrefix?: "as-needed" | "always" | "never"; // Default: "as-needed"
  detection?: {
    cookie?: boolean;        // Default: true
    browserLanguage?: boolean; // Default: true
    cookieName?: string;     // Default: "locale"
    cookieMaxAge?: number;   // Default: 31536000 (1 year)
    explicitCookieName?: string; // Default: `${cookieName}_explicit`
  };
}

import type {
  // Main configuration
  I18nConfig,
  I18nMiddlewareConfig,

  // Client-side provider
  BetterI18nProviderProps,

  // Middleware callback types (Clerk-style pattern)
  MiddlewareContext,
  MiddlewareCallback,

  // Language metadata from manifest
  LanguageOption,
  ManifestLanguage,
  ManifestResponse,

  // Locale types
  Locale,
  LocalePrefix,
  LogLevel,

  // Translation messages
  Messages,
} from "@better-i18n/next";

interface MiddlewareContext {
  /** Detected locale from the request */
  locale: string;
  /** Where the locale was resolved from: path > cookie > geo > header > default */
  detectedFrom: "path" | "cookie" | "geo" | "header" | "default";
  /** true when the explicit-marker cookie is present (deliberate user choice) */
  isExplicit: boolean;
  /** The i18n response with headers already set - can be modified */
  response: NextResponse;
}

type MiddlewareCallback = (
  request: NextRequest,
  context: MiddlewareContext
) => Promise<NextResponse | void> | NextResponse | void;

const myCallback: MiddlewareCallback = async (request, { locale, response }) => {
  // Return NextResponse to short-circuit (e.g., redirect)
  // Return void to continue with i18n response
};

interface LanguageOption {
  code: string; // "en", "tr", etc.
  name?: string; // "English", "Turkish"
  nativeName?: string; // "English", "Türkçe"
  flagUrl?: string | null; // URL to flag image
}

type Messages = Record<string, unknown>;

// Example
const messages: Messages = {
  common: {
    welcome: "Welcome",
    goodbye: "Goodbye",
  },
  errors: {
    notFound: "Page not found",
  },
};