---
createdAt: 2025-09-22
updatedAt: 2025-09-23
title: New Intlayer v7 - What's new?
description: Discover what's new in Intlayer v7. Major improvements in performance, developer experience, and new features to enhance your internationalization workflow.
keywords:
  - Intlayer
  - Localization
  - Development
  - Performance
  - Developer Experience
  - Features
  - React
  - Next.js
  - JavaScript
  - TypeScript
slugs:
  - doc
  - releases
  - v7
---

# New Intlayer v7 - What's new?

Welcome to Intlayer v7! This major release introduces significant improvements in performance, type safety, and developer experience. Below are the highlights, with migration notes and practical examples.

## Table of contents

<TOC levels={[2]} maxDepth={1} />

## Highlights

- Next.js 16 support
- Caching strategy for faster builds
- Improved TypeScript type generation with locale-specific types
- Bundle optimization: Locales as strings instead of enum
- New routing modes: `prefix-no-default`, `prefix-all`, `no-prefix`, `search-params`
- GDPR-compliant using localStorage
- Flexible storage configuration: cookies, localStorage, sessionStorage, or multiple
- 30% smaller Visual Editor package size
- Enhanced middleware configuration options
- Updated fill command behavior for better content management
- New dictionary configuration section for better organization
- Enhanced stability with complete content declaration file updates
- Intelligent retry management for translation accuracy
- Parallelization for faster translation processing
- Smart chunking to handle large files within AI context limits
- Automatic code formatting with configurable formatCommand

---

## Performance: Caching for faster builds

Instead of rebuilding content declarations with esbuild on every build, v7 implements a caching strategy that speeds up the build process.

```bash packageManager="npm"
npx intlayer build
```

```bash packageManager="yarn"
yarn intlayer build
```

```bash packageManager="pnpm"
pnpm intlayer build
```

```bash packageManager="bun"
bun x intlayer build
```

The new caching system:

- Stores compiled content declarations to avoid redundant processing
- Detects changes and rebuilds only modified files
- Significantly reduces build times for large projects

---

## TypeScript: Locale-specific type generation

TypeScript types are now generated per locale, providing stronger typing and eliminating union types across all locales.

**v6 behavior:**

```tsx
const content = getIntlayer("my-title-content", "en");
// typeof content = { title: "My title" } | { title: "Mon titre" } | { title: "Mi título" }
```

**v7 behavior:**

```tsx
const content = getIntlayer("my-title-content", "en");
// typeof content = { title: "My title" }
```

Benefits:

- More precise autocomplete in your IDE
- Better type safety with no cross-locale type pollution
- Improved performance by reducing type complexity

---

## Bundle optimization: Locales as strings

The `Locales` type is no longer an enum, which means it's now fully tree-shakeable and won't bloat your bundle with thousands of unused locale records.

**v6:**

```typescript
import { Locales } from "intlayer";
// Enum including all locales -> not tree-shakeable

const locale: Locales = Locales.ENGLISH;
```

**v7:**

```typescript
import { Locales, Locale } from "intlayer";
// String type -> fully tree-shakeable

const locale: Locale = Locales.ENGLISH;
```

> Because `Locales` is not an enum anymore, you will have to change the type from `Locales` to `Locale` to get the locale as a type.

See the [implementation details](https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/types/src/index.ts) for more information.

---

## New routing modes for greater flexibility

v7 introduces a unified `routing.mode` configuration that replaces the previous `prefixDefault` and `noPrefix` options, offering more granular control over URL structure.

### Available routing modes

- **`prefix-no-default`** (default): Default locale has no prefix, other locales do
  - `/dashboard` (en) or `/fr/dashboard` (fr)
- **`prefix-all`**: All locales have a prefix
  - `/en/dashboard` (en) or `/fr/dashboard` (fr)
- **`no-prefix`**: No locale prefixes in URLs (locale handled via storage/headers)
  - `/dashboard` for all locales
- **`search-params`**: Locale passed as a query parameter
  - `/dashboard?locale=en` or `/dashboard?locale=fr`

### Basic configuration

```typescript
// intlayer.config.ts
export default {
  internationalization: {
    locales: ["en", "fr", "es"],
    defaultLocale: "en",
  },
  routing: {
    mode: "prefix-no-default", // default
  },
};
```

---

## GDPR compliance: localStorage / cookies storage

v7 prioritizes user privacy by using `localStorage` as the default storage mechanism instead of cookies. This change helps with GDPR compliance by avoiding cookie consent requirements for locale preferences.

### Storage configuration options

The new `routing.storage` field is also available in addition to the previous `middleware.cookieName` and `middleware.serverSetCookie` options, offering flexible storage configurations:

```typescript
// Disable storage
storage: false

// Simple storage types
storage: 'cookie'
storage: 'localStorage'
storage: 'sessionStorage'

// Cookie with custom attributes
storage: {
  type: 'cookie',
  name: 'custom-locale',
  domain: '.example.com',
  secure: true,
  sameSite: 'strict'
}

// localStorage with custom key
storage: {
  type: 'localStorage',
  name: 'custom-locale'
}

// Multiple storage types for redundancy
storage: ['cookie', 'localStorage']
```

### GDPR-compliant configuration example

For production applications that need to balance functionality with GDPR compliance:

```typescript fileName="intlayer.config.ts"
export default {
  internationalization: {
    locales: ["en", "fr", "es"],
    defaultLocale: "en",
  },
  routing: {
    mode: "prefix-no-default",
    storage: [
      {
        type: "localStorage", // Primary storage (no consent needed)
        name: "user-locale",
      },
      {
        type: "cookie", // Optional cookie storage (requires consent)
        name: "user-locale",
        secure: true,
        sameSite: "strict",
        httpOnly: false,
      },
    ],
  },
};
```

### Enable / disable the cookie storage

Example using React / Next.js:

Can be defined globally:

```typescript
<IntlayerProvider isCookieEnabled={false}>
  <App />
</IntlayerProvider>
```

Can override it locally for each hook:

```ts
const { setLocale } = useLocale({ isCookieEnabled: false });

setLocale("en");
```

**Note:** Cookies is enabled by default.
**Note:** Check [GDPR cookie requirements](https://gdpr.eu/cookies/) for your specific use case.

---

## Visual Editor: 30% smaller package

The Visual Editor package has been optimized to be 30% smaller than the previous version, thanks to:

- Code editor performance improvements
- Removal of unnecessary dependencies on Intlayer core packages
- Better tree-shaking and module bundling

This results in faster download times and improved runtime performance for your application.

---

## Automatic Code Formatting: formatCommand configuration

v7 introduces the `formatCommand` option in the editor configuration, allowing you to automatically format content files when they are written by Intlayer. This ensures consistent code style and formatting across your content declaration files.

If not set, Intlayer will try to detect the format command automatically. By trying to resolve the following commands: prettier, biome, eslint.

### Configuration

The `formatCommand` option accepts a string template where `{{file}}` will be replaced with the actual file path:

```typescript fileName="intlayer.config.ts"
export default {
  content: {
    formatCommand: 'bun x biome format "{{file}}" --write --log-level none',
  },
};
```

### Supported formatters

You can use any code formatter that accepts file paths as arguments:

**Using Biome:**

```typescript
formatCommand: 'bun x biome format "{{file}}" --write --log-level none';
```

**Using Prettier:**

```typescript
formatCommand: 'npx prettier --write "{{file}}" --log-level silent';
```

**Using ESLint:**

```typescript
formatCommand: 'npx eslint --fix "{{file}}" --quiet';
```

**Using Bun's built-in formatter:**

```typescript
formatCommand: 'bun format "{{file}}"';
```

### Benefits

- **Consistent formatting**: All content files are automatically formatted according to your project's style guidelines
- **Developer experience**: No need to manually format files after Intlayer writes them
- **Team consistency**: Ensures all team members have the same formatting applied to content files
- **CI/CD integration**: Content files maintain consistent formatting in automated workflows

### How it works

When Intlayer writes or updates a content declaration file (`.content.ts`, `.content.js`, etc.), it automatically runs the specified format command on the file. The `{{file}}` placeholder is replaced with the actual file path, and the command is executed in the project's base directory.

---

## Dictionary Configuration: Better organization and structure

v7 introduces a new dedicated `dictionary` configuration section that provides better organization for dictionary-related settings and improved content management.

### New dictionary configuration structure

The `fill` property has been moved from the `content` section to a new `dictionary` section, providing clearer separation of concerns:

**v6 configuration:**

```typescript fileName="intlayer.config.ts"
export default {
  content: {
    autoFill: "./{{fileName}}.content.json",
    contentDir: ["src"],
  },
};
```

**v7 configuration:**

```typescript fileName="intlayer.config.ts"
export default {
  content: {
    contentDir: ["src"],
  },
  dictionary: {
    fill: "./{{fileName}}.content.json",
  },
};
```

### Benefits of the new structure

- **Clearer organization**: Dictionary-specific settings are now grouped together
- **Better separation of concerns**: Content discovery vs. dictionary operations are clearly separated
- **Enhanced maintainability**: Easier to understand and modify dictionary-related configurations
- **Future extensibility**: The dictionary section can accommodate additional dictionary-specific settings
- **Comprehensive dictionary management**: Includes properties like `title`, `live`, `priority`, `tags`, `version`, and `description` for creating and managing new dictionaries

### Configuration usage

The dictionary configuration serves two main purposes:

1. **Default Values**: Define default values when creating content declaration files
2. **Fallback Behavior**: Provide fallback values when specific fields are not defined, allowing you to define dictionary operation behavior globally

The dictionary section includes comprehensive properties for dictionary management:

- **`fill`**: Auto-fill behavior for content generation
- **`title`**: Default title for new dictionaries
- **`live`**: Live sync configuration for real-time updates
- **`priority`**: Priority settings for dictionary resolution
- **`tags`**: Default tags for content organization
- **`version`**: Version management for dictionary updates
- **`description`**: Default description for new content

For more information about content declaration files and how configuration values are applied, see the [Content File Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/content_file.md).

---

## Fill command: Updated behavior for better content management

v7 introduces improved behavior for the `fill` command, providing more predictable and flexible content management:

### New fill behavior

- **`fill: true`** - Rewrites the current file with filled content for all locales
- **`fill: "path/to/file"`** - Fills the specified file without modifying the current file
- **`fill: false`** - Disables auto-fill completely

### Enhanced support for complex content structures

The fill command now supports complex content declaration structures, including:

- **Composed objects**: Content declarations that reference other objects
- **Destructured content**: Content that uses destructuring patterns
- **Nested references**: Objects that call each other in complex hierarchies
- **Dynamic content structures**: Content with conditional or computed properties

### Benefits

- **Clearer intent**: The behavior is now more explicit about what gets modified
- **Better separation**: Content files can be kept separate from filled translations
- **Improved workflow**: Developers have more control over where translations are stored
- **Complex structure support**: Handle sophisticated content architectures with multiple interconnected objects

### Example usage

```typescript fileName="*.content.ts"
// Rewrite current file with all locales
const content = {
  key: "example",
  fill: true, // Rewrites this file
  content: {
    title: "Hello World",
  },
};

// Fill separate file without modifying current file
const content = {
  key: "example",
  fill: "./translations.json", // Creates/updates translations.json
  content: {
    title: "Hello World",
  },
};

// Disable auto-fill
const content = {
  key: "example",
  fill: false, // No auto-fill
  content: {
    title: "Hello World",
  },
};

// Complex content structure with composed objects
const sharedContent = {
  buttons: {
    save: "Save",
    cancel: "Cancel",
  },
};

const content = {
  key: "complex-example",
  fill: true,
  content: {
    // References to other objects
    sharedContent,

    // Destructured content
    ...sharedContent,

    // Nested references
    sections: [
      {
        ...sharedContent.buttons,
        header: "Section 1",
      },
    ],
  },
};
```

---

## Enhanced stability and translation management

v7 introduces several improvements to make content translation more reliable and efficient:

### Complete content declaration file updates

The system now updates `.content.{ts,js,cjs,mjs}` files rather than partial updates, ensuring:

- **Data integrity**: Complete file rewrites prevent partial updates that could corrupt content
- **Consistency**: All locales are updated atomically, maintaining synchronization
- **Reliability**: Reduces the risk of incomplete or malformed content files

### Intelligent retry management

New retry mechanisms prevent pushing content in incorrect formats, and avoid breaking the whole fill process if one request fails.

### Parallelization for faster processing

Translation operations now run in a queue to run them in parallel. This significantly speeds up the process.

### Smart chunking for large files

Advanced chunking strategies handle large content files without exceeding AI context windows:

### Example workflow

```typescript fileName="*.content.ts"
// Large content file gets automatically chunked
const content = {
  key: "large-documentation",
  fill: true,
  content: {
    // Large content automatically chunked for AI processing
    introduction: "..." // 5000+ characters
    sections: [
      // Multiple large sections
    ]
  }
};
```

The system automatically:

1. Analyzes content size and structure
2. Chunks content appropriately
3. Processes chunks in parallel
4. Validates and retries if needed
5. Reconstructs the complete file

---

## Migration notes from v6

### Removed configurations

- **`middleware.cookieName`**: Replaced by `routing.storage`
- **`middleware.serverSetCookie`**: Replaced by `routing.storage`
- **`middleware.prefixDefault`**: Replaced by `routing.mode`
- **`middleware.noPrefix`**: Replaced by `routing.mode`

### New configurations

- **`editor.formatCommand`**: New option for automatic code formatting of content files

### Migration mapping

#### Configuration mapping

| v6 Configuration           | v7 Configuration                                     |
| -------------------------- | ---------------------------------------------------- |
| `content.autoFill: xxx`    | `dictionary.fill: xxx`                               |
| `prefixDefault: false`     | `mode: 'prefix-no-default'`                          |
| `prefixDefault: true`      | `mode: 'prefix-all'`                                 |
| `noPrefix: true`           | `mode: 'no-prefix'`                                  |
| `cookieName: 'my-locale'`  | `storage: { type: 'cookie', name: 'my-locale' }`     |
| `serverSetCookie: 'never'` | `storage: false` or remove cookie from storage array |

#### Example migration

**Before (v6):**

```typescript fileName="intlayer.config.ts"
export default {
  content: {
    autoFill: "./{{fileName}}.content.json",
    contentDir: ["src"],
  },
  middleware: {
    headerName: "x-intlayer-locale",
    cookieName: "intlayer-locale",
    prefixDefault: false,
    basePath: "",
    serverSetCookie: "always",
    noPrefix: false,
  },
};
```

**After (v7):**

```typescript fileName="intlayer.config.ts"
export default {
  content: {
    contentDir: ["src"],
  },
  dictionary: {
    fill: "./{{fileName}}.content.json",
  },
  routing: {
    mode: "prefix-no-default",
    storage: "localStorage", // or 'cookie' if you need cookie storage
    headerName: "x-intlayer-locale",
    basePath: "",
  },
  editor: {
    formatCommand: 'bun x biome format "{{file}}" --write --log-level none', // Optional: automatic formatting
  },
};
```

#### Dictionary content mapping

| v6 Dictionary content | v7 Dictionary content |
| --------------------- | --------------------- |
| `autoFill: xxx`       | `fill: xxx`           |

#### Example migration

**Before (v6):**

```typescript fileName="*.content.ts"
const content = {
  key: "example",
  autoFill: true, // Rewrites this file
  content: {
    title: "Hello World",
  },
};
```

**After (v7):**

```typescript fileName="*.content.ts"
const content = {
  key: "example",
  fill: true, // Rewrites this file
  content: {
    title: "Hello World",
  },
};
```

---

## Migration notes from v5 to v6

Check the [migration notes from v5 to v6](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/releases/v6.md) for more information.

---

## Useful links

- [Configuration Reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md)
- [Middleware Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/next-intlayer/index.md)
- [TypeScript Types](https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/types/src/index.ts)
- [GDPR Cookie Guidelines](https://gdpr.eu/cookies/)
