@intlayer/docs 8.3.0-canary.4 → 8.3.1

package/docs/en/intlayer_with_vite+vue.md

@@ -957,64 +957,165 @@ import RouterLink from "@components/RouterLink.vue";
 </template>
 ```
 
-### (Optional) Step 11: Render Markdown
+### (Optional) Step 11: Extract the content of your components
 
-Intlayer supports rendering Markdown content directly in your Vue application. By default, Markdown is treated as plain text. To convert Markdown into rich HTML, you can integrate [markdown-it](https://github.com/markdown-it/markdown-it), a Markdown parser.
+If you have an existing codebase, transforming thousands of files can be time-consuming.
 
-This is particularly useful when your translations include formatted content like lists, links, or emphasis.
+To ease this process, Intlayer propose a [compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compiler.md) / [extractor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/extract.md) to transform your components and extract the content.
 
-By default Intlayer render markdown as string. But Intlayer also provides a way to render markdown into HTML using the `installIntlayerMarkdown` function.
+To set it up, you can add a `compiler` section in your `intlayer.config.ts` file:
 
-> To see how to declare markdown content using the `intlayer` package, see the [markdown doc](https://github.com/aymericzip/intlayer/tree/main/docs/en/dictionary/markdown.md).
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import { type IntlayerConfig } from "intlayer";
 
-```ts fileName="main.ts"
-import MarkdownIt from "markdown-it";
-import { createApp, h } from "vue";
-import { installIntlayer, installIntlayerMarkdown } from "vue-intlayer";
+const config: IntlayerConfig = {
+  // ... Rest of your config
+  compiler: {
+    /**
+     * Indicates if the compiler should be enabled.
+     */
+    enabled: true,
+
+    /**
+     * Defines the output files path
+     */
+    output: ({ fileName, extension }) => `./${fileName}${extension}`,
+
+    /**
+     * 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,
+
+    /**
+     * Dictionary key prefix
+     */
+    dictionaryKeyPrefix: "",
+  },
+};
 
-const app = createApp(App);
+export default config;
+```
 
-installIntlayer(app);
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  // ... Rest of your config
+  compiler: {
+    /**
+     * Indicates if the compiler should be enabled.
+     */
+    enabled: true,
+
+    /**
+     * Defines the output files path
+     */
+    output: ({ fileName, extension }) => `./${fileName}${extension}`,
+
+    /**
+     * 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,
+
+    /**
+     * Dictionary key prefix
+     */
+    dictionaryKeyPrefix: "",
+  },
+};
 
-const md = new MarkdownIt({
-  html: true, // allow HTML tags
-  linkify: true, // auto-link URLs
-  typographer: true, // enable smart quotes, dashes, etc.
-});
+export default config;
+```
 
-// Tell Intlayer to use md.render() whenever it needs to turn markdown into HTML
-installIntlayerMarkdown(app, (markdown) => {
-  const html = md.render(markdown);
-  return h("div", { innerHTML: html });
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  // ... Rest of your config
+  compiler: {
+    /**
+     * Indicates if the compiler should be enabled.
+     */
+    enabled: true,
+
+    /**
+     * Defines the output files path
+     */
+    output: ({ fileName, extension }) => `./${fileName}${extension}`,
+
+    /**
+     * 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,
+
+    /**
+     * Dictionary key prefix
+     */
+    dictionaryKeyPrefix: "",
+  },
+};
+
+module.exports = config;
+```
+
+<Tabs>
+ <Tab value='Extract command'>
+
+Run the extractor to transform your components and extract the content
+
+```bash packageManager="npm"
+npx intlayer extract
+```
+
+```bash packageManager="pnpm"
+pnpm intlayer extract
+```
+
+```bash packageManager="yarn"
+yarn intlayer extract
+```
+
+```bash packageManager="bun"
+bunx intlayer extract
+```
+
+ </Tab>
+ <Tab value='Babel compiler'>
+
+Update your `vite.config.ts` to include the `intlayerCompiler` plugin:
+
+```ts fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { intlayer, intlayerCompiler } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [
+    intlayer(),
+    intlayerCompiler(), // Adds the compiler plugin
+  ],
 });
 ```
 
-Once registered, you can use the component-based syntax to display the Markdown content directly:
+```bash packageManager="npm"
+npm run build # Or npm run dev
+```
 
-```vue
-<script setup lang="ts">
-import { useIntlayer } from "vue-intlayer";
+```bash packageManager="pnpm"
+pnpm run build # Or pnpm run dev
+```
 
-const { myMarkdownContent } = useIntlayer("my-component");
-</script>
+```bash packageManager="yarn"
+yarn build # Or yarn dev
+```
 
-<template>
-  <div>
-    <!-- Basic syntax -->
-    <myMarkdownContent />
-
-    <!-- Or with custom components -->
-    <component
-      :is="
-        myMarkdownContent.use({
-          h1: (props) => h('h1', { style: { color: 'red' } }, props.children),
-        })
-      "
-    />
-  </div>
-</template>
+```bash packageManager="bun"
+bun run build # Or bun run dev
 ```
 
+ </Tab>
+</Tabs>
+
 ### Configure TypeScript
 
 Intlayer uses module augmentation to get benefits of TypeScript and make your codebase stronger.

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.
@@ -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
 
@@ -1046,7 +1085,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 +1109,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`: