Configuration
All configuration options for @better-i18n/next
The createI18n function is the entry point for the SDK. It accepts a configuration object that defines your project context and delivery preferences.
Basic Configuration
The absolute minimum required is your project indentifier and default locale.
import { createI18n } from "@better-i18n/next";
export const i18n = createI18n({
projectId: "your-org/your-project",
defaultLocale: "en",
});You can also configure CLI-specific options (like linting rules and file exclusions) in this same file. See CLI Configuration for details.
Full Reference
| Option | Type | Default | Description |
|---|---|---|---|
project | string | required | Project identifier in org/project format |
defaultLocale | string | required | Default/fallback locale code |
cdnBaseUrl | string | auto | CDN base URL (auto-detected) |
localePrefix | "as-needed" | "always" | "never" | "as-needed" | URL locale prefix behavior |
debug | boolean | false | Enable debug logging |
logLevel | LogLevel | "warn" | Logging verbosity |
manifestCacheTtlMs | number | 300000 | Manifest cache TTL in ms |
manifestRevalidateSeconds | number | 3600 | Next.js revalidate for manifest |
messagesRevalidateSeconds | number | 30 | Next.js revalidate for messages |
cookieName | string | "locale" | Name of the locale persistence cookie |
explicitCookieName | string | `${cookieName}_explicit` | Cookie written by useSetLocale to mark a deliberate choice (match middleware's detection.explicitCookieName) |
timeZone | string | System tz | IANA timezone. Set explicitly to avoid ENVIRONMENT_FALLBACK warnings and prevent SSR/client hydration mismatches. |
storage | TranslationStorage | — | Persistent storage adapter (offline fallback) |
staticData | Record<string, Messages> | (() => Promise<...>) | — | Last-resort bundled translations for offline use |
fetchTimeout | number | 10000 | CDN fetch timeout in ms |
retryCount | number | 1 | Retry attempts on CDN failure |
namespaces | string[] | — | Default namespaces to fetch on every call (namespaced_folders projects only). See Selective Loading. |
Behavior Customization
Control how locales appear in your URLs.
"as-needed" (default) — Only non-default locales get a prefix. Clean URLs for your primary language.
// /about (English), /tr/about (Turkish)
createI18n({ projectId: "org/project", defaultLocale: "en", localePrefix: "as-needed" });"always" — Every URL includes the locale, including the default. Best for explicit SEO signals.
// /en/about, /tr/about
createI18n({ projectId: "org/project", defaultLocale: "en", localePrefix: "always" });"never" — No locale in URLs. Locale is determined by cookie and Accept-Language header.
// /about for all locales
createI18n({ projectId: "org/project", defaultLocale: "en", localePrefix: "never" });"never" mode requires specific file structure and middleware behavior. See Middleware — Locale Prefix Modes for the full setup guide.
Configure TTL for edge and runtime caching.
createI18n({
projectId: "org/project",
defaultLocale: "en",
// Cache manifest in memory for 5 minutes
manifestCacheTtlMs: 5 * 60 * 1000,
// Next.js ISR revalidation times
manifestRevalidateSeconds: 3600,
messagesRevalidateSeconds: 30,
});Enable detailed logging for troubleshooting.
createI18n({
projectId: "org/project",
defaultLocale: "en",
debug: true,
logLevel: "debug",
});