---
title: Configuration
description: 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.

```ts title="i18n.config.ts"
import { createI18n } from "@better-i18n/next";

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

<Callout type="info">
The `project` value uses `org/project` format. This same value is used by the [CLI](/cli) and [MCP](/mcp) to identify your project.
</Callout>

<Callout type="tip">
You can also configure CLI-specific options (like linting rules and file exclusions) in this same file. See [CLI Configuration](/cli/configuration) for details.
</Callout>

## 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 |
| `namespaces` | `string[]` | — | Default namespaces to fetch on every call (namespaced_folders projects only). See [Selective Loading](/docs/core/selective-loading). |

---

## Behavior Customization

<Tabs items={['Locale Prefix', 'Caching', 'Debug Mode']}>
  <Tab value="Locale Prefix">
    Control how locales appear in your URLs.

    **`"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" });
    ```

    <Callout type="warn">
      `"never"` mode requires specific file structure and middleware behavior. See [Middleware — Locale Prefix Modes](/frameworks/nextjs/middleware#locale-prefix-modes) for the full setup guide.
    </Callout>
  </Tab>
  <Tab value="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,

      // Next.js ISR revalidation times
      manifestRevalidateSeconds: 3600,
      messagesRevalidateSeconds: 30,
    });
    ```
  </Tab>
  <Tab value="Debug Mode">
    Enable detailed logging for troubleshooting.
    ```ts
    createI18n({
      projectId: "org/project",
      defaultLocale: "en",
      debug: true,
      logLevel: "debug",
    });
    ```
  </Tab>
</Tabs>
