Next.js
API Reference
Detailed API documentation for @better-i18n/next
Complete API reference for the Next.js SDK.
Architecture
@better-i18n/next is built on top of @better-i18n/core and adds Next.js-specific optimizations:
- ISR (Incremental Static Regeneration) - Automatic cache revalidation via
next.revalidate - Manifest caching - 1 hour default (3600s)
- Messages caching - 30 seconds default for fast updates
Middleware
createI18n
The main entry point for the SDK. Returns an object with everything needed for Next.js i18n integration.
import { createI18n } from "@better-i18n/next";
const i18n = createI18n({
project: "org/project",
defaultLocale: "en",
// Optional
localePrefix: "as-needed", // "as-needed" | "always" | "never"
manifestRevalidateSeconds: 3600, // ISR for manifest
messagesRevalidateSeconds: 30, // ISR for messages
debug: false,
});Return Properties
createNextI18nCore
Low-level factory that wraps @better-i18n/core with Next.js ISR support. Use this when you need direct access to the core instance.
import { createNextI18nCore } from "@better-i18n/next";
const i18nCore = createNextI18nCore({
project: "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();Server Utilities
Import from @better-i18n/next/server:
import {
createNextIntlRequestConfig,
getManifest,
getMessages,
getLocales,
getManifestLanguages,
} from "@better-i18n/next/server";Client Utilities
Import from @better-i18n/next/client:
import {
BetterI18nProvider,
useSetLocale,
useManifestLanguages,
} from "@better-i18n/next/client";Configuration
I18nConfig
Main configuration type for createI18n and server utilities.
interface I18nConfig {
// Required
project: string; // "org/project" format
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"
// 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";
}I18nMiddlewareConfig
Configuration for createBetterI18nMiddleware.
interface I18nMiddlewareConfig {
project: 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)
};
}