Intlayer Compiler | Automated Content Extraction for i18n

What is the Intlayer Compiler?

The Intlayer Compiler is a powerful tool designed to automate the process of internationalisation (i18n) in your applications. It scans your source code (JSX, TSX, Vue, Svelte) for content declarations, extracts them, and automatically generates the necessary dictionary files. This allows you to keep your content co-located with your components while Intlayer handles the management and synchronisation of your dictionaries.

Why Use the Intlayer Compiler?

• Automation: Eliminates manual copy-pasting of content into dictionaries.
• Speed: Optimised content extraction ensuring your build process remains fast.
• Developer Experience: Keep content declarations right where they are used, improving maintainability.
• Live Updates: Supports Hot Module Replacement (HMR) for instant feedback during development.

See the Compiler vs. Declarative i18n blog post for a deeper comparison.

Why not use the Intlayer Compiler?

Whilst the compiler offers an excellent "just works" experience, it also introduces some trade-offs you should be aware of:

• Heuristic ambiguity: The compiler must guess what is user-facing content vs. application logic (e.g., className="active", status codes, product IDs). In complex codebases, this can lead to false positives or missed strings that require manual annotations and exceptions.
• Static-only extraction: Compiler-based extraction relies on static analysis. Strings that only exist at runtime (API error codes, CMS fields, etc.) cannot be discovered or translated by the compiler alone, so you still need a complementary runtime i18n strategy.

For a deeper architectural comparison, see the blog post Compiler vs. Declarative i18n.

As an alternative, to automate your i18n process whilst keeping full control of your content, Intlayer also provides an auto-extraction command intlayer extract (see CLI documentation), or the Intlayer: extract content to Dictionary command from the Intlayer VS Code extension (see VS Code extension documentation).

Usage

npm install vite-intlayer

import { defineConfig } from "vite";import { intlayer, intlayerCompiler } from "vite-intlayer";export default defineConfig({ plugins: [   intlayer(),   intlayerCompiler(), // Adds the compiler plugin ],});

# For Vuenpm install @intlayer/vue-compiler# For Sveltenpm install @intlayer/svelte-compiler

npm install @intlayer/babel

const { intlayerExtractBabelPlugin, intlayerOptimizeBabelPlugin, getExtractPluginOptions, getOptimizePluginOptions,} = require("@intlayer/babel");module.exports = { presets: ["next/babel"], plugins: [   // Extract content from components into dictionaries   [intlayerExtractBabelPlugin, getExtractPluginOptions()],   // Optimize imports by replacing useIntlayer with direct dictionary imports   [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()], ],};

Custom config

To customise the compiler behaviour, you can update the intlayer.config.ts file in the root of your project.

import { type IntlayerConfig, Locales } from "intlayer";const config: IntlayerConfig = {  compiler: {    /**     * Indicates if the compiler should be enabled.     * Set to 'build-only' to skip the compiler during development and speed up start times.     */    enabled: true,    /**     * Defines the output files path. Replaces `outputDir`.     *     * - Paths starting with `./` are resolved relatively to the component directory.     * - Paths starting with `/` are resolved relatively to the project root (`baseDir`).     *     * - Including the `{{locale}}` variable in the path will enable the generation of dictionaries separated by locale.     *     * Examples:     * ```ts     * {     *   // Create multi-locale .content.ts files next to the component     *   output: ({ fileName, extension }) => `./${fileName}${extension}`,     *     *   // output: './{{fileName}}{{extension}}', // Equivalent using string template     * }     * ```     *     * ```ts     * {     *   // Create centralized JSON files by locale in the project root     *   output: ({ key, locale }) => `/locales/${locale}/${key}.content.json`,     *     *   // output: '/locales/{{locale}}/{{key}}.content.json', // Equivalent using string template     * }     * ```     *     * List of variables:     *   - `fileName`: The file name.     *   - `key`: The content key.     *   - `locale`: The content locale.     *   - `extension`: The file extension.     *   - `componentFileName`: The component file name.     *   - `componentExtension`: The component file extension.     *   - `format`: The dictionary format.     *   - `componentFormat`: The component dictionary format.     *   - `componentDirPath`: The component directory path.     */    output: ({ fileName, extension }) => `./${fileName}${extension}`,    /**     * Indicates if the components should be saved after being transformed.     *     * - If `true`, the compiler will rewrite the component file in the disk. So the transformation will be permanent, and the compiler will skip the transformation for the next process. That way, the compiler can transform the app, and then it can be removed.     *     * - If `false`, the compiler will inject the `useIntlayer()` function call into the code in the build output only, and keep the base codebase intact. The transformation will be done only in memory.     */    saveComponents: false,    /**     * Inset only content in generated file. Useful for i18next or ICU MessageFormat JSON output per locale.     *     * - `output: ({ locale, key }) => `./locale/${locale}/${key}.json`,`     */    noMetadata: false,    /**     * Dictionary key prefix     */    dictionaryKeyPrefix: "", // Add an optional prefix for the extracted dictionary keys  },};

Compiler Configuration Reference

The following properties can be configured in the compiler block of your intlayer.config.ts file:

• enabled:

  • Type: boolean | 'build-only'
  • Default: true
  • Description: Indicates if the compiler should be enabled.

• dictionaryKeyPrefix:

  • Type: string
  • Default: ''
  • Description: Prefix for the extracted dictionary keys.

• transformPattern:

  • Type: string | string[]
  • Default: ['**/*.{js,ts,mjs,cjs,jsx,tsx,vue,svelte}', '!**/node_modules/**']
  • Description: (Deprecated: use build.traversePattern instead) Patterns to traverse the code to optimise.

• excludePattern:

  • Type: string | string[]
  • Default: ['**/node_modules/**']
  • Description: (Deprecated: use build.traversePattern instead) Patterns to exclude from the optimisation.

• output:

  • Type: FilePathPattern
  • Default: ({ key }) => 'compiler/${key}.content.json'
  • Description: Defines the output files path. Replaces outputDir. Handles dynamic variables like {{locale}}, {{key}}, {{fileName}}, {{extension}}, {{format}}, {{dirPath}}, {{componentFileName}}, {{componentExtension}}, {{componentFormat}}. Can be set as a string using 'my/{{var}}/path' format, or as a function.
  • Note: ./**/* Path are resolved relatively to the component. /**/* path are resolved relatively to the Intlayer baseDir.
  • Note: If the locale is defined in the path, the dictionaries will be generated by locale.
  • Example: output: ({ locale, key }) => 'compiler/${locale}/${key}.json'

• noMetadata:

  • Type: boolean
  • Default: false
  • Description: Indicates if the metadata should be saved in the file. If true, the compiler will not save the metadata of the dictionaries (key, content wrapper). Useful for per-locale i18next or ICU MessageFormat JSON outputs.
  • Note: Useful if used with loadJSON plugin.
  • Example: If true: json { "key": "value" } If false: json { "key": "value", "content": { "key": "value" } }

• saveComponents:

  • Type: boolean
  • Default: false
  • Description: Indicates if the components should be saved after being transformed.

Fill missing translation

Intlayer provide a CLI tool to help you fill missing translations. You can use the intlayer command to test and fill missing translations from your code.

npx intlayer test         # Test if there is missing translations

npx intlayer fill         # Fill missing translations

Extraction

Intlayer provides a CLI tool to extract content from your code. You can use the intlayer extract command to extract the content from your code.

npx intlayer extract

For more details, refer to the CLI documentation