---
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 internationalisation workflow.
keywords:
  - Intlayer
  - Localisation
  - 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.

## Highlights

- Caching strategy for faster builds
- Improved TypeScript type generation with locale-specific types
- Bundle optimisation: 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 behaviour for better content management
- Enhanced stability with complete content declaration file updates
- Intelligent retry management for translation accuracy
- Parallelisation for faster translation processing
- Smart chunking to handle large files within AI context limits

---

## 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
npx 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 behaviour:**

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

**v7 behaviour:**

```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 optimisation: Locales as strings

The `Locales` type is no longer an enum, which means it is now fully tree-shakeable and will not 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 prioritises 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
// 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 are 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 optimised 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.

---

## Fill command: Updated behaviour for better content management

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

### New fill behaviour

- **`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 behaviour 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
// 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 synchronisation
- **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.

### Parallelisation 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
// 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. Analyses 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`

### Migration mapping

#### Configuration mapping

| v6 Configuration           | v7 Configuration                                     |
| -------------------------- | ---------------------------------------------------- |
| `autoFill: xxx`            | `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
export default {
  middleware: {
    headerName: "x-intlayer-locale",
    cookieName: "intlayer-locale",
    prefixDefault: false,
    basePath: "",
    serverSetCookie: "always",
    noPrefix: false,
  },
};
```

**After (v7):**

```typescript
export default {
  routing: {
    mode: "prefix-no-default",
    storage: "localStorage", // or 'cookie' if you require cookie storage
    headerName: "x-intlayer-locale",
    basePath: "",
  },
};
```

#### Dictionary content mapping

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

#### Example migration

**Before (v6):**

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

**After (v7):**

```typescript
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-GB/releases/v6.md) for more information.

---

## Useful links

- [Configuration Reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md)
- [Middleware Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/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/)