intlayer Vite Plugin

The intlayer plugin is the single entry-point for integrating Intlayer into a Vite application. Register it once and everything works out of the box: dictionary compilation, module aliases, dev-server watching, locale-routing middleware, and production build optimisations.

Usage

// vite.config.ts
import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

export default defineConfig({
  plugins: [intlayer()],
});

Options

import type { IntlayerPluginOptions } from "vite-intlayer";

IntlayerPluginOptions extends GetConfigurationOptions (see @intlayer/config) with the following additional fields:

All other options (override, configFile, …) are forwarded directly to getConfiguration().

Examples

Ignore API routes from locale routing

// vite.config.ts
import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

export default defineConfig({
  plugins: [
    intlayer({
      proxy: {
        ignore: (req) => req.url?.startsWith("/api"),
      },
    }),
  ],
});

With a custom config file path

export default defineConfig({
  plugins: [
    intlayer({
      configFile: "./config/intlayer.config.ts",
    }),
  ],
});

With compat-adapter callers

import { intlayer } from "vite-intlayer";
import { reactI18nextCallerConfig } from "@intlayer/react-i18next/plugin";

export default defineConfig({
  plugins: [
    intlayer({
      compatCallers: [reactI18nextCallerConfig],
    }),
  ],
});

What the plugin does

1. Dictionary preparation

Before the build starts (and once per hour in dev), intlayer calls prepareIntlayer to compile all .content.ts files into optimised JSON dictionaries stored in .intlayer/.

2. Module aliases

The plugin adds Vite resolve aliases so that import { myDict } from 'intlayer/dictionaries/my-dict' resolves to the compiled JSON file on disk. SSR builds use ssr.noExternal to ensure all @intlayer/* packages are bundled with aliases applied.

3. Dev-server watcher

In development mode a chokidar watcher is started. When a .content.ts file changes the dictionaries are recompiled and Vite's HMR propagates the update to the browser.

4. Bundled locale-routing proxy (v9+)

Since Intlayer v9 the intlayerProxy middleware is registered automatically inside intlayer(). It handles:

• Locale detection from URL prefix, cookies, and Accept-Language header.
• 301 redirects when the detected locale does not match the current URL.
• Internal URL rewrites so the framework sees the correct [locale] route parameter.

The proxy is controlled by routing.enableProxy (default true) in your Intlayer config. To disable it completely:

// intlayer.config.ts
import { defineConfig } from "intlayer";

export default defineConfig({
  routing: { enableProxy: false },
});

To customise proxy behaviour without a separate intlayerProxy() call, pass proxy options to the main plugin:

intlayer({ proxy: { ignore: (req) => req.url?.startsWith("/api") } });

See the intlayerProxy documentation for the full routing behaviour reference.

5. Bundled compiler (v9+)

When compiler.enabled is true and compiler.output is set in your Intlayer config, intlayer() registers intlayerCompiler automatically. The compiler extracts inline content declarations written directly inside component files and writes them to dictionaries at transform time. See intlayerCompiler documentation.

6. Build optimisations

During a production build the plugin adds:

• intlayerOptimize – Babel transform that rewrites useIntlayer('key') → useDictionary(hash) and injects direct JSON imports.
• intlayerPrune – removes unused content fields from dictionary JSON.
• intlayerMinify – compacts dictionary JSON and optionally mangles field names.

These are inactive in development mode.

Deprecated aliases