Configuration

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({
  project: "your-org/your-project",
  defaultLocale: "en",
});

The project value uses org/project format. This same value is used by the CLI and MCP to identify your project.

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
`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

Behavior Customization

Control how locales appear in your URLs.

// /page for default, /tr/page for others
createI18n({ project: "org/project", defaultLocale: "en", localePrefix: "as-needed" });

// always includes locale: /en/page, /tr/page
createI18n({ project: "org/project", defaultLocale: "en", localePrefix: "always" });

// never includes locale in URL
createI18n({ project: "org/project", defaultLocale: "en", localePrefix: "never" });

Configure TTL for edge and runtime caching.

createI18n({
  project: "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({
  project: "org/project",
  defaultLocale: "en",
  debug: true,
  logLevel: "debug",
});

Basic Configuration

Full Reference

Behavior Customization

On this page