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 internationalization (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 synchronization of your dictionaries.

Why Use the Intlayer Compiler?

• Automation: Eliminates manual copy-pasting of content into dictionaries.

• Speed: Optimized 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?

While 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 while 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 customize the compiler behavior, 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 are resolved relative to the component directory.     * - `/` paths are resolved relative to the project root (`baseDir`).     *     * - Including the `{{locale}}` variable in the path will trigger the generation of separate dictionaries per locale.     *     * Example:     * ```ts     * {     *   // Create Multilingual .content.ts files close to the component     *   output: ({ fileName, extension }) => `./${fileName}${extension}`,     *     *   // output: './{{fileName}}{{extension}}', // Equivalent using template string     * }     * ```     *     * ```ts     * {     *   // Create centralize per-locale JSON at the root of the project     *   output: ({ key, locale }) => `/locales/${locale}/${key}.content.json`,     *     *   // output: '/locales/{{locale}}/{{key}}.content.json', // Equivalent using template string     * }     * ```     *     * Variable list:     *   - `fileName`: The name of the file.     *   - `key`: The key of the content.     *   - `locale`: The locale of the content.     *   - `extension`: The extension of the file.     *   - `componentFileName`: The name of the component file.     *   - `componentExtension`: The extension of the component file.     *   - `format`: The format of the dictionary.     *   - `componentFormat`: The format of the component dictionary.     *   - `componentDirPath`: The directory path of the component.     */    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 into the generated file. Useful for per-locale i18next or ICU MessageFormat JSON outputs.     *     * - `output: ({ locale, key }) => `./locale/${locale}/${key}.json`,`     */    noMetadata: false,    /**     * Dictionary key prefix     */    dictionaryKeyPrefix: "", // Add an optional prefix for the extracted dictionary keys  },};export default config;

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

• excludePattern:

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

• 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 locale is set in the path, it will generate per-locale dictionaries.
  • 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.
    • If true, the compiler will rewrite the component file in the disk. The transformation will be permanent, and the compiler can then 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.

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

Extract

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

npx intlayer extract

For more details, refer to the CLI documentation