@intlayer/docs 8.3.0 → 8.3.2

package/docs/en-GB/compiler.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-09-09
-updatedAt: 2026-03-10
+updatedAt: 2026-03-12
 title: Intlayer Compiler | Automated Content Extraction for i18n
 description: Automate your internationalisation process with the Intlayer Compiler. Extract content directly from your components for faster, more efficient i18n in Vite, Next.js, and more.
 keywords:
@@ -149,59 +149,83 @@ This configuration ensures that content declared in your components is automatic
 See complete tutorial: [Intlayer Compiler with Next.js](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_nextjs_compiler.md)
 
  </Tab>
+</Tabs>
 
 ### Custom config
 
 To customise the compiler behaviour, you can update the `intlayer.config.ts` file in the root of your project.
 
-```ts fileName="intlayer.config.ts"
+````ts fileName="intlayer.config.ts"
 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,
 
     /**
-     * Pattern to traverse the code to optimize.
+     * 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.
      */
-    transformPattern: [
-      "**/*.{js,ts,mjs,cjs,jsx,tsx,vue,svelte}",
-      "!**/node_modules/**",
-    ],
+    output: ({ fileName, extension }) => `./${fileName}${extension}`,
 
     /**
-     * Pattern to exclude from the optimization.
-     */
-    excludePattern: ["**/node_modules/**"],
-
-    /**
-     * Output directory for the optimized dictionaries.
+     * Indicates if the components should be saved after being transformed.
+     * That way, the compiler can be run only once to transform the app, and then it can be removed.
      */
-    output: ({ key }) => `compiler/${key}.content.json`,
+    saveComponents: false,
 
     /**
-     * Inset only content in generated file, without key.
+     * 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: "", // Remove base prefix
-
-    /**
-     * Indicates if the components should be saved after being transformed.
-     * That way, the compiler can be run only once to transform the app, and then it can be removed.
-     */
-    saveComponents: false,
+    dictionaryKeyPrefix: "", // Add an optional prefix for the extracted dictionary keys
   },
 };
-
-export default config;
-```
+````
 
 ### Compiler Configuration Reference
 
@@ -211,34 +235,34 @@ The following properties can be configured in the `compiler` block of your `intl
   - _Type_: `boolean | 'build-only'`
   - _Default_: `true`
   - _Description_: Indicates if the compiler should be enabled.
+
 - **dictionaryKeyPrefix**:
   - _Type_: `string`
-  - _Default_: `'comp-'`
+  - _Default_: `''`
   - _Description_: Prefix for the extracted dictionary keys.
+
 - **transformPattern**:
   - _Type_: `string | string[]`
   - _Default_: `['**/*.{js,ts,mjs,cjs,jsx,tsx,vue,svelte}', '!**/node_modules/**']`
-  - _Description_: Patterns to traverse the code to optimize.
+  - _Description_: (Deprecated: use `build.traversePattern` instead) Patterns to traverse the code to optimise.
+
 - **excludePattern**:
   - _Type_: `string | string[]`
   - _Default_: `['**/node_modules/**']`
-  - _Description_: Patterns to exclude from the optimization.
-- **outputDir** (Deprecated):
-  - _Type_: `string`
-  - _Default_: `'compiler'`
-  - _Description_: The directory where the extracted dictionaries will be stored.
+  - _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).
+  - _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`:
@@ -274,4 +298,12 @@ npx intlayer test         # Test if there is missing translations
 npx intlayer fill         # Fill missing translations
 ```
 
-> For more details, refer to the [CLI documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/ci.md)
+### 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.
+
+```bash
+npx intlayer extract
+```
+
+> For more details, refer to the [CLI documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/index.md)

package/docs/en-GB/configuration.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-03-11
+updatedAt: 2026-03-12
 title: Configuration
 description: Learn how to configure Intlayer for your application. Understand the various settings and options available to customise Intlayer to your needs.
 keywords:
@@ -15,7 +15,7 @@ slugs:
   - configuration
 history:
   - version: 8.3.0
-    data: 2026-03-11
+    date: 2026-03-11
     changes: Move 'baseDir' from 'content' to 'system' config
   - version: 8.2.0
     date: 2026-03-09
@@ -92,7 +92,7 @@ Intlayer accepts JSON, JS, MJS, and TS configuration file formats:
 
 ## Example config file
 
-```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+````typescript fileName="intlayer.config.ts" codeFormat="typescript"
 import { Locales, type IntlayerConfig } from "intlayer";
 import { nextjsRewrite } from "intlayer/routing";
 import { z } from "zod";
@@ -190,7 +190,7 @@ const config: IntlayerConfig = {
      * Options: 'cookie', 'localStorage', 'sessionStorage', 'header', or an array of these.
      * Default: ['cookie', 'header']
      */
-    storage: "cookie",
+    storage: ["cookie", "header"],
 
     /**
      * Base path for the application URLs.
@@ -256,13 +256,13 @@ const config: IntlayerConfig = {
   editor: {
     /**
      * Whether the visual editor is enabled.
-     * Default: true
+     * Default: false
      */
     enabled: true,
 
     /**
      * URL of your application for origin validation.
-     * Default: "*"
+     * Default: ""
      */
     applicationURL: "http://localhost:3000",
 
@@ -327,6 +327,17 @@ const config: IntlayerConfig = {
      * Base URL for the AI API.
      */
     baseURL: "http://localhost:3000",
+
+    /**
+     * Data serialisation
+     *
+     * Options:
+     * - "json": Standard, reliable; uses more tokens.
+     * - "toon": Fewer tokens, less consistent than JSON.
+     *
+     * Default: "json"
+     */
+    dataSerialization: "json",
   },
 
   /**
@@ -426,42 +437,70 @@ const config: IntlayerConfig = {
   compiler: {
     /**
      * Indicates if the compiler should be enabled.
+     *
+     * - false : Disables the compiler.
+     * - true : Enables the compiler.
+     * - "build-only" : Skips the compiler during development to speed up start times.
+     *
+     * Default: false
      */
     enabled: true,
 
     /**
-     * Pattern to traverse the code to optimize.
+     * 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 trigger the generation of separate dictionaries per locale.
+     *
+     * Examples:
+     * ```ts
+     * {
+     *   // Create multi-locale .content.ts files next to the component
+     *   output: ({ fileName, extension }) => `./${fileName}${extension}`,
+     *
+     *   // output: './{{fileName}}{{extension}}', // Equivalent using a string template
+     * }
+     * ```
+     *
+     * ```ts
+     * {
+     *   // Create centralised JSON files by locale in the project root
+     *   output: ({ key, locale }) => `/locales/${locale}/${key}.content.json`,
+     *
+     *   // output: '/locales/{{locale}}/{{key}}.content.json', // Equivalent using a 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.
      */
-    transformPattern: [
-      "**/*.{js,ts,mjs,cjs,jsx,tsx,vue,svelte}",
-      "!**/node_modules/**",
-    ],
+    output: ({ locale, key }) => `compiler/${locale}/${key}.json`,
 
     /**
-     * Pattern to exclude from the optimization.
-     */
-    excludePattern: ["**/node_modules/**"],
-
-    /**
-     * Output directory for the optimized dictionaries.
+     * Indicates if the components should be saved after being transformed.
+     * That way, the compiler can be run only once to transform the app, and then it can be removed.
      */
-    output: ({ key }) => `compiler/${key}.content.json`,
+    saveComponents: false,
 
     /**
-     * Inset only content in generated file, without key.
+     * Insert only content into the generated file. Useful for per-locale i18next or ICU MessageFormat JSON outputs.
      */
     noMetadata: false,
 
     /**
      * Dictionary key prefix
      */
-    dictionaryKeyPrefix: "", // Remove base prefix
-
-    /**
-     * Indicates if the components should be saved after being transformed.
-     * That way, the compiler can be run only once to transform the app, and then it can be removed.
-     */
-    saveComponents: false,
+    dictionaryKeyPrefix: "", // Add optional prefix for the extracted dictionary keys
   },
 
   /**
@@ -480,7 +519,7 @@ const config: IntlayerConfig = {
 };
 
 export default config;
-```
+````
 
 ## Configuration Reference
 
@@ -994,25 +1033,6 @@ Build options apply to the `@intlayer/babel` and `@intlayer/swc` plugins.
   - _Note_: This option relies on the `@intlayer/babel` and `@intlayer/swc` plugins.
   - _Note_: Ensure all keys are declared statically in the `useIntlayer` calls. e.g. `useIntlayer('navbar')`.
 
-- **importMode**:
-  - _Note_: **Deprecated**: Use `dictionary.importMode` instead.
-  - _Type_: `'static' | 'dynamic' | 'fetch'`
-  - _Default_: `'static'`
-  - _Description_: Controls how dictionaries are imported.
-  - _Example_: `'dynamic'`
-  - _Note_: Available modes:
-    - "static": Dictionaries are imported statically. Replaces `useIntlayer` with `useDictionary`.
-    - "dynamic": Dictionaries are imported dynamically using Suspense. Replaces `useIntlayer` with `useDictionaryDynamic`.
-    - "fetch": Dictionaries are fetched dynamically using the live sync API. Replaces `useIntlayer` with `useDictionaryFetch`.
-  - _Note_: Dynamic imports rely on Suspense and may slightly affect rendering performance.
-  - _Note_: If disabled, all locales will be loaded at once, even if they are not used.
-  - _Note_: This option relies on the `@intlayer/babel` and `@intlayer/swc` plugins.
-  - _Note_: Ensure all keys are declared statically in the `useIntlayer` calls, e.g. `useIntlayer('navbar')`.
-  - _Note_: This option will be ignored if `optimize` is disabled.
-  - _Note_: If set to "fetch", only the dictionaries that include remote content and are flagged as "live" will be transformed into fetch mode. Others will be imported dynamically as "dynamic" mode to optimise the number of fetch queries and load performance.
-  - _Note_: Fetch mode will use the live sync API to fetch the dictionaries. If the API call fails, the dictionaries will be imported dynamically as "dynamic" mode.
-  - _Note_: This option will not affect the `getIntlayer`, `getDictionary`, `useDictionary`, `useDictionaryAsync` and `useDictionaryDynamic` functions.
-
 - **outputFormat**:
   - _Type_: `'esm' | 'cjs'`
   - _Default_: `'esm'`
@@ -1046,7 +1066,7 @@ Settings that control the Intlayer compiler, which extracts dictionaries straigh
 
 - **dictionaryKeyPrefix**:
   - _Type_: `string`
-  - _Default_: `'comp-'`
+  - _Default_: `''`
   - _Description_: Prefix for the extracted dictionary keys.
   - _Example_: `'my-key-'`
   - _Note_: When dictionaries are extracted, the key is generated based on the file name. This prefix is added to the generated key to prevent conflicts.
@@ -1070,22 +1090,25 @@ Settings that control the Intlayer compiler, which extracts dictionaries straigh
   - _Description_: Patterns that define which files should be excluded during optimisation.
   - _Example_: `['**/node_modules/**', '!**/node_modules/react/**']`
 
-- **outputDir**:
-  - _Type_: `string`
-  - _Default_: `'compiler'`
-  - _Description_: The directory where the extracted dictionaries will be stored, relative to your project base path.
-
 - **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`.
-  - _Example_: `output: ({ locale, key }) => 'compiler/${locale}/${key}.json'`
+  - _Default_: `undefined`
+  - _Description_: Defines the output files path. Replaces `outputDir`. Supports dynamic variables via a template string or a function. Supported variables: `{{fileName}}`, `{{key}}`, `{{locale}}`, `{{extension}}`, `{{componentFileName}}`, `{{componentExtension}}`, `{{format}}`, `{{componentFormat}}`, `{{componentDirPath}}`.
+  - _Note_: Paths starting with `./` are resolved relatively to the component directory. Paths starting with `/` are resolved relatively to the project root (`baseDir`).
+  - _Note_: Including the `{{locale}}` variable in the path will enable the generation of separate dictionaries per locale.
+  - _Example_:
+    - **Create multi-locale files next to the component**:
+    - String: `'./{{fileName}}{{extension}}'`
+    - Function: `({ fileName, extension }) => \`./${fileName}${extension}\``
+
+    - **Output centralised JSON files per locale**:
+    - String: `'/locales/{{locale}}/{{key}}.content.json'`
+    - Function: `({ key, locale }) => \`/locales/${locale}/${key}.content.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).
+  - _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`:

package/docs/en-GB/intlayer_with_analog.md

@@ -342,7 +342,7 @@ It is recommended to ignore the files generated by Intlayer. This allows you to
 
 To do this, you can add the following instructions to your `.gitignore` file:
 
-```plaintext
+```bash
 # Ignore the files generated by Intlayer
 .intlayer
 ```

package/docs/en-GB/intlayer_with_angular.md

@@ -398,7 +398,7 @@ It is recommended to ignore the files generated by Intlayer. This allows you to
 
 To do this, you can add the following instructions to your `.gitignore` file:
 
-```plaintext
+```bash
 # Ignore the files generated by Intlayer
 .intlayer
 ```

package/docs/en-GB/intlayer_with_astro.md

@@ -218,7 +218,7 @@ It is recommended to ignore the files generated by Intlayer. This allows you to
 
 To do this, you can add the following instructions to your `.gitignore` file:
 
-```plaintext
+```bash
 # Ignore the files generated by Intlayer
 .intlayer
 ```

package/docs/en-GB/intlayer_with_lynx+react.md

@@ -538,7 +538,7 @@ This is what enables features like:
 
 To avoid committing auto-generated files by Intlayer, add the following to your `.gitignore`:
 
-```plaintext
+```bash
 # Ignore the files generated by Intlayer
 .intlayer
 ```

package/docs/en-GB/intlayer_with_react_native+expo.md

@@ -628,7 +628,7 @@ This enables features such as:
 
 To prevent committing auto-generated files by Intlayer, add the following to your `.gitignore`:
 
-```plaintext
+```bash
 # Ignore the files generated by Intlayer
 .intlayer
 ```

package/docs/en-GB/intlayer_with_vite+preact.md

@@ -1333,7 +1333,7 @@ It is recommended to ignore the files generated by Intlayer. This allows you to
 
 To do this, you can add the following instructions to your `.gitignore` file:
 
-```plaintext
+```bash
 # Ignore the files generated by Intlayer
 .intlayer
 ```

package/docs/en-GB/intlayer_with_vite+react.md

@@ -1665,7 +1665,7 @@ It is recommended to ignore the files generated by Intlayer. This prevents you f
 
 To do this, you can add the following instructions to your `.gitignore` file:
 
-```plaintext
+```bash
 # Ignore the files generated by Intlayer
 .intlayer
 ```

package/docs/en-GB/intlayer_with_vite+solid.md

@@ -553,7 +553,7 @@ It is recommended to ignore the files generated by Intlayer. This allows you to
 
 To do this, you can add the following instructions to your `.gitignore` file:
 
-```plaintext
+```bash
 # Ignore the files generated by Intlayer
 .intlayer
 ```

package/docs/en-GB/intlayer_with_vite+svelte.md

@@ -470,7 +470,7 @@ It is recommended to ignore the files generated by Intlayer. This prevents you f
 
 To do this, you can add the following instructions to your `.gitignore` file:
 
-```plaintext
+```bash
 # Ignore the files generated by Intlayer
 .intlayer
 ```

package/docs/en-GB/intlayer_with_vite+vue.md

@@ -1106,7 +1106,7 @@ It is recommended to ignore the files generated by Intlayer. This allows you to
 
 To do this, you can add the following instructions to your `.gitignore` file:
 
-```plaintext
+```bash
 # Ignore the files generated by Intlayer
 .intlayer
 ```
@@ -1128,7 +1128,7 @@ It is recommended to ignore the files generated by Intlayer. This allows you to
 
 To do this, you can add the following instructions to your `.gitignore` file:
 
-```plaintext
+```bash
 # Ignore the files generated by Intlayer
 .intlayer
 ```

package/docs/en-GB/vs_code_extension.md

@@ -120,7 +120,7 @@ The extension can load environment variables from your workspace to run Intlayer
 
 #### Selecting the active environment
 
-- **Command Palette**: open the palette and run `Intlayer: Select Environment`, then choose the environment (e.g., `development`, `staging`, `production`). The extension will attempt to load the first available file in the priority list above and show a notification like “Loaded env from .env.<env>.local”.
+- **Command Palette**: open the palette and run `Intlayer: Select Environment`, then choose the environment (e.g., `development`, `staging`, `production`). The extension will attempt to load the first available file in the priority list above and show a notification like “Loaded env from `.env.<env>.local`”.
 - **Settings**: go to `Settings → Extensions → Intlayer`, and set:
   - **Environment**: the environment name used to resolve `.env.<env>*` files.
   - (Optional) **Env File**: an explicit path to a `.env` file. When provided, it takes precedence over the inferred list.