Configuration — Better I18N

本页内容

Basic Configuration
Full Reference
Behavior Customization

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.

i18n.config.ts

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

export const i18n = createI18n({
  projectId: "your-org/your-project",
  defaultLocale: "en",
});

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 #

Locale Prefix

Control how locales appear in your URLs.

Code

**`"as-needed"`** (default) — Only non-default locales get a prefix. Clean URLs for your primary language.
```ts
// /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.
```ts
// /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.
```ts
// /about for all locales
createI18n({ projectId: "org/project", defaultLocale: "en", localePrefix: "never" });
```

> [!WARNING]

"never" mode requires specific file structure and middleware behavior. See Middleware — Locale Prefix Modes for the full setup guide.

Caching

Configure TTL for edge and runtime caching. ```ts createI18n({ projectId: "org/project", defaultLocale: "en", // Cache manifest in memory for 5 minutes manifestCacheTtlMs: 5 * 60 * 1000,

Code

  // Next.js ISR revalidation times
  manifestRevalidateSeconds: 3600,
  messagesRevalidateSeconds: 30,
});
```

Debug Mode

Enable detailed logging for troubleshooting. ts createI18n({ projectId: "org/project", defaultLocale: "en", debug: true, logLevel: "debug", });