Optimizing i18n Bundle Size & Performance

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 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 might result in a user downloading the content of 100 pages, 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 optimization. It analyzes your code to detect which dictionaries are actually used per component and reinjects only the necessary content into your bundle.

Table of Contents

Scan your bundle

Analyzing your bundle is the first step in identifying "heavy" JSON files and code-splitting opportunities. These tools generate a visual treemap of your application's compiled code, allowing you to see exactly which libraries are consuming 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:

1. Analyzes your code to find useIntlayer calls.
2. Builds the corresponding dictionary content.
3. Replaces the useIntlayer call with optimized 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.

Setup by Platform

npm install -D @intlayer/swc

npm install -D @intlayer/babel

const { getOptimizePluginOptions, intlayerOptimizeBabelPlugin,} = require("@intlayer/babel");module.exports = { plugins: [[intlayerOptimizeBabelPlugin, getOptimizePluginOptions()]],};

Configuration

You can control how Intlayer optimizes 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: {    /**     * Minify the dictionaries to reduce the bundle size.     */     minify: true;    /**     * Purge the unused keys in a dictionaries     */     purge: true;    /**     * Indicates if the build should check TypeScript types     */    checkTypes: false;  },};export default config;

Keeping the default option for optimize is recommended in the most majority of cases.

See doc configuration for more details: Configuration

Build Options

The following options are available under the build configuration object:

Minification

Minifying dictionaries removes unnecessary whitespace, comments, and reduces the size of the JSON content. This is especially useful for large dictionaries.

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

Note: Minification is ignored if optimize is disabled or if the Visual Editor is enabled (as the editor needs the full content to allow editing).

Purging

Purging ensures that only the keys actually used in your code are included in the final dictionary bundle. This can significantly reduce the size of your bundle if you have large dictionaries with many keys that are not used in every part of your application.

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

Note: Purging is ignored if optimize is disabled.

Import Mode

For large applications, including several pages and locales, your JSON can represent a significant 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 by default 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 fine-grained definition

As well as for each dictionaries in your .content.{{ts|tsx|js|jsx|mjs|cjs|json|jsonc|json5}} 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 dictates how the dictionary content is injected into your component. You can define it globally in the intlayer.config.ts file under the dictionary object, or you can overwrite it for a specific dictionary 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 extra 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");// Optimized code illustration after transformation (Static)// This is only for illustration purposes, the actual code will be different for optimization reasonsconst content = useDictionary({  key: "my-key",  content: {    nodeType: "translation",    translation: {      en: "My title",      fr: "Mon titre",    },  },});

2. Dynamic Mode

In dynamic mode, Intlayer replaces useIntlayer with useDictionaryAsync. This uses import() (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 only download 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");// Optimized code illustration after transformation (Dynamic)// This is only for illustration purposes, the actual code will be different for optimization 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) rather than one per atom component. You can also use multiple .content files using 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");// Optimized 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 can't be used.

Summary: Static vs Dynamic