i18n Bundle Size & Performance Optimisation

One of the most common challenges with traditional i18n solutions relying on JSON files is managing content size. If developers do not manually separate content into namespaces, users often end up downloading the translations for every page and potentially every language just to view a single page.

For example, an application with 10 pages translated into 10 languages could result in a user downloading 100 pages' worth of content, even though they only need one (the current page in the current language). This leads to wasted bandwidth and slower load times.

Intlayer solves this problem through build-time optimisation. It analyses your code to detect exactly which dictionaries are actually used per component and re-injects only the necessary content into your bundle.

Table of Contents

Analyse your bundle

Analysing your bundle is the first step to identifying "heavy" JSON files and opportunities for code-splitting. These tools generate a visual treemap of your application's compiled code, allowing you to see exactly which libraries are taking up the most space.

npm install -D rollup-plugin-visualizer

import { defineConfig } from "vite";import { visualizer } from "rollup-plugin-visualizer";export default defineConfig({ plugins: [   visualizer({     open: true, // Automatically open the report in your browser     filename: "stats.html",     gzipSize: true,     brotliSize: true,   }), ],});

npx next experimental-analyze

npm install -D @next/bundle-analyzer

const withBundleAnalyzer = require("@next/bundle-analyzer")({ enabled: process.env.ANALYZE === "true",});module.exports = withBundleAnalyzer({ // Your Next.js config});

ANALYZE=true npm run build

npm install -D webpack-bundle-analyzer

import { BundleAnalyzerPlugin } from "webpack-bundle-analyzer";export default { plugins: [   new BundleAnalyzerPlugin({     analyzerMode: "static",     reportFilename: "bundle-analyzer.html",     openAnalyzer: false,   }), ],};

How it works

Intlayer uses a per-component approach. Unlike global JSON files, your content is defined alongside or within your components. During the build process, Intlayer will:

1. Analyse your code to find useIntlayer calls.
2. Build the corresponding dictionary content.
3. Replace the useIntlayer call with optimised code based on your configuration.

This ensures that:

• If a component is not imported, its content is not included in the bundle (Dead Code Elimination).
• If a component is lazy-loaded, its content is also lazy-loaded.

Plugin Reference

Intlayer's build optimisation is split into several discrete plugins, each with a single responsibility. Understanding what each one does prevents confusion when configuring them.

Babel plugins (@intlayer/babel)

These are used directly in babel.config.js for Webpack-based setups (Next.js with Babel, CRA, custom Webpack, etc).

Plugin order matters. In your babel.config.js the purge and minify plugins must appear before the optimize plugin. The optimize pass replaces useIntlayer('key') with an opaque useDictionary(hash) call, wiping out the dictionary key information the purge and minify passes need to identify which fields are used.

Each Babel plugin has a corresponding options helper that reads your intlayer.config.ts once at config load time and returns pre-resolved values:

Vite plugins (vite-intlayer)

Vite users never configure these directly. They are wired up automatically when you call withIntlayer() in vite.config.ts. The build.purge and build.minify flags in intlayer.config.ts toggle the corresponding behaviour without any extra plugin registration.

Setup by Platform

npm install -D @intlayer/swc

npm install -D @intlayer/babel

const { intlayerPurgeBabelPlugin, intlayerMinifyBabelPlugin, getPurgePluginOptions, getMinifyPluginOptions,} = require("@intlayer/babel");module.exports = { presets: ["next/babel"], plugins: [   // Purge: remove unused content fields from .intlayer/**/*.json   [intlayerPurgeBabelPlugin, getPurgePluginOptions()],   // Minify: rename content field keys in JSON + source code   [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],   // Note: intlayerOptimizeBabelPlugin is NOT needed here because   // @intlayer/swc handles the useIntlayer → useDictionary rewrite. ],};

import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = { build: {   purge: true, // remove unused content fields from bundled JSON   minify: true, // rename content field keys to short aliases },};export default config;

npm install -D @intlayer/babel

const { intlayerExtractBabelPlugin, intlayerPurgeBabelPlugin, intlayerMinifyBabelPlugin, intlayerOptimizeBabelPlugin, getExtractPluginOptions, getPurgePluginOptions, getMinifyPluginOptions, getOptimizePluginOptions,} = require("@intlayer/babel");module.exports = { plugins: [   // Extract: compile .content.ts files → .intlayer/**/*.json   [intlayerExtractBabelPlugin, getExtractPluginOptions()],   // Purge: remove unused fields from .intlayer/**/*.json   //    (reads the intlayer.config.ts build.purge flag)   [intlayerPurgeBabelPlugin, getPurgePluginOptions()],   // Minify: rename field keys in JSON + source code   //    (reads the intlayer.config.ts build.minify flag)   [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],   // Optimize: rewrite useIntlayer('key') → useDictionary(hash)   //    Must come last because it erases the dictionary key.   [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()], ],};

Configuration

You can control how Intlayer optimises your bundle via the build property in your intlayer.config.ts.

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.FRENCH],    defaultLocale: Locales.ENGLISH,  },  dictionary: {    importMode: "dynamic",  },  build: {    // Replace useIntlayer() calls with direct dictionary imports at build-time.    // undefined = auto (enabled in production), true = always, false = never.    optimize: undefined,    // Rename content field keys in compiled dictionaries to short alphabetical    // aliases (e.g. title → a). Reduces JSON size; requires optimize.    minify: true,    // Remove content fields that are never accessed in the source code.    // Requires optimize.    purge: true,  },};export default config;

It is recommended to keep the default value (undefined) for optimize in most cases.

See the configuration reference for all options: Configuration

Build Options

Minification (field key rename)

build.minify does not minify your JavaScript bundle — your bundler handles that. Instead, it shrinks the compiled dictionary JSON files by replacing every user-defined content field key with a short alphabetical alias:

// Before minification{ "title": "Hello", "subtitle": "World" }// After minification{ "a": "Hello", "b": "World" }

The same rename is applied to all property accesses in your source code, so content.title becomes content.a in the compiled output. The runtime behaviour is identical.

import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  build: {    minify: true,  },};export default config;

Minification is skipped when optimize is false or when editor.enabled is true (the visual editor requires the original field names to allow editing).

Minification is also skipped for dictionaries loaded via importMode: 'fetch' because their JSON is served from a remote API using the original field names — renaming the client-side keys would break the server/client contract.

Purging (unused field removal)

build.purge analyses which content fields are actually accessed in your source code and removes all others from the compiled JSON files.

import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  build: {    purge: true,  },};export default config;

Example: a dictionary with five fields where only two are used:

// Before purge{ "title": "…", "subtitle": "…", "cta": "…", "footer": "…", "badge": "…" }// After purge (only title + subtitle accessed in source){ "title": "…", "subtitle": "…" }

Purge is skipped when optimize is false or when editor.enabled is true.

Purge is also conservatively skipped when a source file cannot be parsed, or when the result of useIntlayer is assigned to a variable and passed around in ways the static analyser cannot track (e.g. spread into an object, passed as a prop without destructuring). In those cases, the full dictionary is preserved.

Import Mode

For large applications, including several pages and locales, your JSON can represent an important part of your bundle size. Intlayer allows you to control how dictionaries are loaded using the importMode option.

Global definition

The import mode can be defined globally in your intlayer.config.ts file.

import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  dictionary: {    importMode: "dynamic", // Default is 'static'  },};export default config;

Per-dictionary definition

You can override the import mode for individual dictionaries in their .content.{{ts|tsx|js|jsx|mjs|cjs|json|jsonc|json5|md|mdx|yaml|yml}} files.

import { type Dictionary, t } from "intlayer";const appContent: Dictionary = {  key: "app",  importMode: "dynamic", // Override the default import mode  content: {    // ...  },};export default appContent;

The importMode setting determines how the dictionary's content is injected into your component. You can define it globally in intlayer.config.ts under the dictionary object, or override it on a per-dictionary basis in its .content.ts file.

1. Static Mode (default)

In static mode, Intlayer replaces useIntlayer with useDictionary and injects the dictionary directly into the JavaScript bundle.

• Pros: Instant rendering (synchronous), zero additional network requests during hydration.
• Cons: The bundle includes translations for all available languages for that specific component.
• Best for: Single Page Applications (SPA).

Transformed code example:

// Your codeconst content = useIntlayer("my-key");// Optimised code illustration after transformation (Static)// This is for illustration only, the actual code will differ for optimisation reasonsconst content = useDictionary({  key: "my-key",  content: {    nodeType: "translation",    translation: {      en: "My title",      fr: "Mon titre",    },  },});

2. Dynamic Mode

In dynamic mode, Intlayer replaces the useIntlayer with useDictionaryAsync. This uses import() (a Suspense-like mechanism) to lazy-load specifically the JSON for the current locale.

• Pros: Locale-level tree shaking. A user viewing the English version will download only the English dictionary. The French dictionary is never loaded.
• Cons: Triggers a network request (asset fetch) per component during hydration.
• Best for: Large text blocks, articles, or applications supporting many languages where bundle size is critical.

Transformed code example:

// Your codeconst content = useIntlayer("my-key");// Optimised code illustration after transformation (Dynamic)// This is for illustration only, the actual code will differ for optimisation reasonsconst content = useDictionaryAsync({  en: () =>    import(".intlayer/dynamic_dictionary/my-key/en.json").then(      (mod) => mod.default    ),  fr: () =>    import(".intlayer/dynamic_dictionary/my-key/fr.json").then(      (mod) => mod.default    ),});

When using importMode: 'dynamic', if you have 100 components using useIntlayer on a single page, the browser will attempt 100 separate fetches. To avoid this "waterfall" of requests, group content into fewer .content files (e.g. one dictionary per page section) instead of one per atom component. You can also use multiple .content files that use the same key. Intlayer will merge them into a single dictionary.

3. Fetch Mode

Behaves similarly to Dynamic mode but attempts to fetch dictionaries from the Intlayer Live Sync API first. If the API call fails or the content is not marked for live updates, it falls back to the dynamic import.

Transformed code example:

// Your codeconst content = useIntlayer("my-key");// Optimised code illustration (Fetch)const content = useDictionaryAsync({  en: () =>    fetch("https://intlayer.my-domain.com/dictionary/my-key/en").then((res) =>      res.json()    ),  fr: () =>    fetch("https://intlayer.my-domain.com/dictionary/my-key/fr").then((res) =>      res.json()    ),});

See CMS documentation for more details: CMS

In fetch mode, purge and minification are not applied because the JSON is served from a remote API using the original field names.

Summary: Static vs Dynamic