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

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.

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 behavior:

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

v7 behavior:

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:

import { Locales } from "intlayer";// Enum including all locales -> not tree-shakeableconst locale: Locales = Locales.ENGLISH;

v7:

import { Locales, Locale } from "intlayer";// String type -> fully tree-shakeableconst 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 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

// intlayer.config.tsexport 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:

// Disable storagestorage: false// Simple storage typesstorage: 'cookie'storage: 'localStorage'storage: 'sessionStorage'// Cookie with custom attributesstorage: {  type: 'cookie',  name: 'custom-locale',  domain: '.example.com',  secure: true,  sameSite: 'strict'}// localStorage with custom keystorage: {  type: 'localStorage',  name: 'custom-locale'}// Multiple storage types for redundancystorage: ['cookie', 'localStorage']

GDPR-compliant configuration example

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

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:

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

Can override it locally for each hook:

const { setLocale } = useLocale({ isCookieEnabled: false });setLocale("en");

Note: Cookies is enabled by default. Note: Check GDPR cookie requirements 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:

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:

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

Using Prettier:

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

Using ESLint:

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

Using Bun's built-in formatter:

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:

export default {  content: {    autoFill: "./{{fileName}}.content.json",    contentDir: ["src"],  },};

v7 configuration:

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.

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

// Rewrite current file with all localesconst content = {  key: "example",  fill: true, // Rewrites this file  content: {    title: "Hello World",  },};// Fill separate file without modifying current fileconst content = {  key: "example",  fill: "./translations.json", // Creates/updates translations.json  content: {    title: "Hello World",  },};// Disable auto-fillconst content = {  key: "example",  fill: false, // No auto-fill  content: {    title: "Hello World",  },};// Complex content structure with composed objectsconst 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

// Large content file gets automatically chunkedconst 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

Example migration

Before (v6):

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):

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

Example migration

Before (v6):

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

After (v7):

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 for more information.

Useful links

• Configuration Reference
• Middleware Documentation
• TypeScript Types
• GDPR Cookie Guidelines