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 locale storage with localStorage as default
• 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.

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:

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

v7 behaviour:

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:

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

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

// intlayer.config.tsexport 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 are enabled by default. Note: Check GDPR cookie requirements 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

// 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 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

// 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. 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

Example migration

Before (v6):

export default {  middleware: {    headerName: "x-intlayer-locale",    cookieName: "intlayer-locale",    prefixDefault: false,    basePath: "",    serverSetCookie: "always",    noPrefix: false,  },};

After (v7):

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

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