---
createdAt: 2025-09-22
updatedAt: 2025-09-23
title: New Intlayer v8 - What's new?
description: Discover what's new in Intlayer v8. Major improvements in developer experience, content validation, and dictionary management.
keywords:
  - Intlayer
  - CMS
  - Developer Experience
  - Features
  - React
  - Next.js
  - JavaScript
  - TypeScript
slugs:
  - doc
  - releases
  - v8
---

# New Intlayer v8 - What's new?

Welcome to Intlayer v8! This release focuses on enhancing developer experience with automatic content detection, ensuring data integrity with schema validation, and providing more control over dictionary management.

## Highlights

- **Compiler Official Release**: The Intlayer compiler, which was in beta in v7, is now officially released with improved stability and performance.
- **HTML Content Support**: New `html()` function to parse and render rich content with custom components.
- **Improved Internationalization API**: New `useIntl()` hook for easy access to locale-aware formatting.
- **Automatic Content Detection**: Markdown and insertion strings are now automatically detected without helper functions.
- **Content Schema Validation**: Enforce content structure using Zod schemas.
- **VSCode Extension Enhancements**: Major updates to the VSCode extension, including unused/duplicated key detection and better resource management.
- **Compiler Optimizations**: Significant performance improvements in the Markdown and HTML compiler through a new caching mechanism.
- **Svelte Improvements**: Markdown and HTML content in Svelte now automatically parse to HTML when stringified, making them easier to use with `{@html}`.
- **Unified Import Mode**: New `importMode` property replaces the `live` boolean for clearer fetching strategies.
- **Dictionary Location Control**: Fine-grained control over local vs. remote dictionaries.
- **System Configuration Separation**: Separation of internal/output directory paths from the content configuration for better clarity.
- **Content and Code Directory Separation**: Split of `contentDir` into `contentDir` (for content definitions) and `codeDir` (for code transformation).

---

## Stability: Official Compiler Release

The Intlayer compiler, which was introduced as a beta feature in v7, is now **officially released**. It has been rewritten for v8 to provide:

- **Improved Stability**: Fixed edge cases in code transformation and content scanning.
- **Better Performance**: Faster builds and reduced memory footprint.
- **Pruning & Optimization**: Enhanced ability to prune unused translations from your client-side bundles, ensuring minimal impact on your application's load time.

---

## Rich Content: HTML Support

Intlayer v8 introduces the `html()` function, allowing you to embed HTML-like content in your dictionaries and map tags to custom components at runtime. This is ideal for rich text that requires more than just Markdown, or when you need to inject interactive components into your content.

**Example:**

```typescript fileName="src/example.content.ts"
import { html } from "intlayer";

export default {
  key: "my-key",
  content: {
    myRichText: html("Click <CustomLink>here</CustomLink> for more info"),
  },
};
```

**Usage in React:**

```tsx
const { myRichText } = useIntlayer("my-key");

return (
  <div>
    {myRichText.use({
      CustomLink: ({ children }) => <a href="/details">{children}</a>,
    })}
  </div>
);
```

---

## Localization: new `useIntl` hook

A new `useIntl()` hook is now available in React, Next.js and Vue. It provides a locale-bound `Intl` object that automatically uses the current language for formatting numbers, dates, and more, without needing to manually pass the locale.

**Example:**

```tsx
const intl = useIntl();

const formattedPrice = new intl.NumberFormat({
  style: "currency",
  currency: "USD",
}).format(123.45);
```

---

## Developer Experience: Automatic Content Detection

In v8, Intlayer intelligently detects Markdown syntax and variable insertions in your content strings. You no longer need to manually wrap strings with `md()` or `insert()` helper functions for simple cases.

**v7 behavior:**

```typescript fileName="src/example.content.ts"
import { md, insert } from "intlayer";

export default {
  key: "my-key",
  content: {
    myMarkdown: md("## Hello World"),
    myInsertion: insert("Hi {{name}}"),
  },
};
```

**v8 behavior:**

```typescript fileName="src/example.content.ts"
export default {
  key: "my-key",
  content: {
    myMarkdown: "## Hello World", // Automatically detected as Markdown
    myInsertion: "Hi {{name}}", // Automatically detected as Insertion
  },
};
```

The underlying JSON result remains the same, preserving the rich type information needed for rendering:

```json
{
  "key": "my-key",
  "content": {
    "myMarkdown": {
      "nodeType": "markdown",
      "markdown": "## Hello World"
    },
    "myInsertion": {
      "nodeType": "insertion",
      "insertion": "Hi {{name}}"
    }
  }
}
```

---

## Data Integrity: Content Schema Validation

Intlayer v8 introduces schema validation for dictionaries. You can now define reusable validation schemas in your configuration using Zod and apply them to your content files. This ensures your content always adheres to the expected structure, catching errors at build time.

### 1. Define Schemas

Define your schemas in `intlayer.config.ts`:

```typescript fileName="intlayer.config.ts"
import { z } from "zod";

export default {
  schemas: {
    "seo-metadata": z.object({
      title: z.string().min(50).max(60),
      description: z.string().min(150).max(160),
    }),
  },
};
```

### 2. Apply Schemas to Dictionaries

Reference the schema key in your dictionary definition:

```typescript fileName="src/example.content.ts"
import { type Dictionary } from "intlayer";

const aboutPageMetaContent = {
  key: "about-page-meta",
  schema: "seo-metadata",
  content: {
    title: "About Our Company - Learn More About Us",
    description: "Discover our company's mission, values, and team.",
  },
} satisfies Dictionary<"seo-metadata">;

export default aboutPageMetaContent;
```

If the content doesn't match the schema (e.g., title is too short), the build process will raise an error.

---

## Tooling: VSCode Extension Enhancements

The Intlayer VSCode extension receives major updates in v8 to streamline your internationalization workflow:

- **Resource Management**: Improved handling of large resource files and better integration with your project's structure.
- **Starting Points**: New "starting point" templates to help you kickstart content declarations for new components.
- **Caching**: Enhanced caching layer for near-instant validation and autocompletion.
- **Content Health Checks**: New features to automatically detect **unused keys** and **duplicated keys** across your dictionaries, helping you keep your content clean and efficient.

---

## Performance: Compiler Optimizations

Intlayer v8 includes a new caching layer for the Markdown and HTML compiler. This ensures that identical content strings with the same configuration are only parsed once, significantly reducing the overhead during re-renders or when using the same content in multiple places.

---

## Framework: Svelte Improvements

Markdown and HTML content in Svelte now automatically parse to HTML when stringified. This makes it much easier to use with Svelte's `{@html}` syntax, as you can now simply pass the content node directly.

---

## Flexibility: Unified Import Mode

The `live` boolean property has been deprecated in favor of a more comprehensive `importMode` property. This allows for explicit definition of how dictionaries should be loaded: statically, dynamically, or via live sync.

### Modes

- **`static`** (Default): Dictionary is bundled at build time. Best for performance.
- **`dynamic`**: Dictionary is loaded at runtime (e.g., via JSON fetch or suspense).
- **`live`**: Dictionary is fetched from the CMS/Server at runtime and synchronized.

**Migration:**

| v7 Config     | v8 Config                             |
| :------------ | :------------------------------------ |
| `live: true`  | `importMode: 'live'`                  |
| `live: false` | `importMode: 'static'` (or 'dynamic') |

**Example:**

```typescript fileName="src/example.content.ts"
export default {
    key: 'my-key',
    importMode: "live", // Overrides global config
    content: { ... }
}
```

---

## Workflow: Dictionary Location Control

v8 introduces the `location` property to explicitly manage where dictionaries live and how they synchronize. This is particularly useful for hybrid workflows involving both local files and remote CMS content.

### Options

- **`local`**: The dictionary exists only locally. It will not be pushed to the remote CMS.
- **`remote`**: The dictionary is managed remotely. It will be pulled from the CMS, and local deletion might occur if removed remotely.
- **`local_and_remote`**: The dictionary exists in both places. Local changes are pushed, and remote changes are pulled (synchronized).

**Example:**

```typescript fileName="src/example.content.ts"
export default {
    key: 'my-key',
    location: "local", // Keep this dictionary local-only
    content: { ... }
}
```

---

## Clarity: System Configuration Separation

Intlayer v8 separates the configuration of content sources from internal system and output paths. This declutters the `content` property and makes it clear which settings are intended for user management vs. those that are managed by the Intlayer system.

The following properties have been moved from `content` to a new `system` property in `intlayer.config.ts`:

- `dictionariesDir`
- `moduleAugmentationDir`
- `unmergedDictionariesDir`
- `typesDir`
- `mainDir`
- `configDir`
- `cacheDir`
- `outputFilesPatternWithPath`

**v7 behavior:**

```typescript fileName="intlayer.config.ts"
export default {
  content: {
    contentDir: ["src"],
    dictionariesDir: ".intlayer/dictionary", // Mixed with source config
  },
};
```

**v8 behavior:**

```typescript fileName="intlayer.config.ts"
export default {
  content: {
    contentDir: ["src"],
  },
  system: {
    dictionariesDir: ".intlayer/dictionary", // Clearly separated
  },
};
```

---

## Performance: Content and Code Directory Separation

Intlayer v8 separates the configuration for content definition files from the configuration for code transformation. This allows for more precise watching and scanning, improving build performance.

Previously, `contentDir` was used for both watching `.content.*` files and scanning code for `useIntlayer` calls. Now:

- **`contentDir`**: Specifically for your content declaration files.
- **`codeDir`**: Specifically for your application code that needs transformation (e.g., pruning, optimization).

**Migration:**

If you previously had `contentDir` set, Intlayer v8 will use it as the default for `codeDir` as well, but will log a warning. You should explicitly define `codeDir` in your configuration.

**v7 behavior:**

```typescript fileName="intlayer.config.ts"
export default {
  content: {
    contentDir: ["src", "@packages/design-system"], // Used for both content and code
  },
};
```

**v8 behavior:**

```typescript fileName="intlayer.config.ts"
export default {
  content: {
    contentDir: ["src/content", "@packages/design-system"], // Only watch for src/content/*.content.* files here and @packages/design-system/dist/*.content.* files
    codeDir: ["src", "@packages/design-system"], // Only scan for code transformation here and @packages/design-system/src/*.content.* files
  },
};
```

---

## Migration notes from v7

### Configuration Changes

- **`live` property**: The `live` property in dictionaries is deprecated. Use `importMode: 'live'` instead.
- **`.set()` to `.use()`**: The `.set()` method for Markdown and HTML overrides has been renamed to `.use()` for better consistency with other framework APIs.
- **`contentDir` and `codeDir`**: `contentDir` is now specifically for content files. A new `codeDir` property has been added for code transformation. If `codeDir` is not set, Intlayer will fallback to `contentDir` and log a warning.
- **Schema Validation**: To use the new `schema` feature, ensure you have `zod` installed in your project.

---

## Useful links

- [Configuration Reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md)
- [Content File Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/content_file.md)
