@intlayer/docs 9.0.0-canary.6 → 9.0.0-canary.8

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

@@ -207,7 +207,13 @@ import { intlayer } from "vite-intlayer";
 
 // https://vitejs.dev/config/
 export default defineConfig({
-  plugins: [intlayer()],
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
 });
 ```
 
@@ -476,12 +482,15 @@ First, add `intlayerProxy` to your Vite config:
 
 ```typescript {3,7} fileName="vite.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import { defineConfig } from "vite";
-import { intlayer, intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
   plugins: [
-    intlayerProxy(), // should be placed first
-    intlayer(),
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 });
 ```

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

@@ -603,14 +603,17 @@ In parallel, you can also use the `intlayerProxy` to add server-side routing to
 ```typescript {3,7} fileName="vite.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import { defineConfig } from "vite";
 import react from "@vitejs/plugin-react-swc";
-import { intlayer, intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 // https://vitejs.dev/config/
 export default defineConfig({
   plugins: [
-    intlayerProxy(), // should be placed first
     react(),
-    intlayer(),
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 });
 ```

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

@@ -207,11 +207,18 @@ Add the intlayer plugin into your configuration.
 ```typescript fileName="vite.config.ts"
 import { defineConfig } from "vite";
 import react from "@vitejs/plugin-react-swc";
-import { intlayer, intlayerCompiler } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 // https://vitejs.dev/config/
 export default defineConfig({
-  plugins: [react(), intlayer(), intlayerCompiler()],
+  plugins: [
+    react(),
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
 });
 ```
 

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

@@ -455,14 +455,17 @@ In parallel, you can also use the `intlayerProxy` to add server-side routing to
 ```typescript {3,7} fileName="vite.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import { defineConfig } from "vite";
 import { svelte } from "@sveltejs/vite-plugin-svelte";
-import { intlayer, intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 // https://vitejs.dev/config/
 export default defineConfig({
   plugins: [
-    intlayerProxy(), // should be placed first
     svelte(),
-    intlayer(),
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 });
 ```

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

@@ -205,7 +205,13 @@ import { intlayer } from "vite-intlayer";
 
 // https://vitejs.dev/config/
 export default defineConfig({
-  plugins: [intlayer()],
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
 });
 ```
 
@@ -466,12 +472,15 @@ First, add `intlayerProxy` to your Vite config:
 
 ```typescript {3,7} fileName="vite.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import { defineConfig } from "vite";
-import { intlayer, intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
   plugins: [
-    intlayerProxy(), // should be placed first
-    intlayer(),
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 });
 ```
@@ -606,6 +615,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel compiler'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 Update your `vite.config.ts` to include the `intlayerCompiler` plugin:
 
 ```ts fileName="vite.config.ts"

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

@@ -627,14 +627,17 @@ In parallel, you can also use the `intlayerProxy` to add server-side routing to
 ```typescript {3,7} fileName="vite.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import { defineConfig } from "vite";
 import vue from "@vitejs/plugin-vue";
-import { intlayer, intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 // https://vitejs.dev/config/
 export default defineConfig({
   plugins: [
-    intlayerProxy(), // should be placed first
     vue(),
-    intlayer(),
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 });
 ```

package/docs/en-GB/packages/@intlayer_babel/export.md

@@ -0,0 +1,131 @@
+---
+createdAt: 2026-06-25
+updatedAt: 2026-06-25
+title: "@intlayer/babel Package Documentation"
+description: Babel plugins for Intlayer to handle content extraction, import optimisation, pruning of unused fields, and mangling of field names during build.
+keywords:
+  - "@intlayer/babel"
+  - babel
+  - plugin
+  - internationalisation
+  - i18n
+  - compiler
+  - optimise
+  - purge
+  - minify
+slugs:
+  - doc
+  - packages
+  - "@intlayer/babel"
+  - export
+history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "Unified documentation of all exports"
+author: aymericzip
+---
+
+# @intlayer/babel Package
+
+The `@intlayer/babel` package provides a set of specialised Babel plugins for Intlayer. These plugins cover the entire build cycle: extracting content declarations, rewriting `useIntlayer` / `getIntlayer` calls to optimised dictionary imports, pruning unused fields, and minifying field names.
+
+## Installation
+
+```bash
+npm install @intlayer/babel
+```
+
+## Exports
+
+Import:
+
+```ts
+import { ... } from "@intlayer/babel";
+```
+
+---
+
+### Plugins
+
+| Function / Class               | Description                                                                                                                                                                                 |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `intlayerExtractBabelPlugin`   | Babel plugin that extracts translatable content from source files and injects `useIntlayer` / `getIntlayer` hooks automatically. Designed for use with Next.js and Babel-based build tools. |
+| `intlayerOptimizeBabelPlugin`  | Babel plugin that transforms `useIntlayer` and `getIntlayer` calls and rewrites their imports to optimised JSON dictionary imports (static, dynamic, or via fetch).                         |
+| `intlayerPurgeBabelPlugin`     | Babel plugin that analyses source files and rewrites compiled dictionary JSON files to remove unused fields (`build.purge`) or rename them to short aliases (`build.minify`).               |
+| `intlayerMinifyBabelPlugin`    | Babel plugin that rewrites source files to use the short field aliases assigned during the minification phase (e.g. `content.title` ← `content.a`). Relies on `intlayerPurgeBabelPlugin`.   |
+| `makeFieldRenameBabelPlugin`   | Factory function that produces a Babel plugin to rename dictionary content field accesses in source files according to the `dictionaryKeyToFieldRenameMap` populated in the `PruneContext`. |
+| `makeUsageAnalyzerBabelPlugin` | Factory function that produces a Babel plugin to analyze the usage of `useIntlayer` / `getIntlayer` in the source code and aggregate field usage data in the shared `PruneContext`.         |
+| `getSharedPruneContext`        | Helper function that returns the shared `PruneContext` object for the specified base directory, or `null` if it has not been initialised yet.                                               |
+
+---
+
+### Plugin Configuration Utilities
+
+| Function                   | Description                                                                                                                                       |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `getExtractPluginOptions`  | Loads the Intlayer configuration and returns `ExtractPluginOptions` ready for use with `intlayerExtractBabelPlugin`.                              |
+| `getOptimizePluginOptions` | Loads the Intlayer configuration and compiled dictionaries, and returns `OptimizePluginOptions` ready for use with `intlayerOptimizeBabelPlugin`. |
+| `getPurgePluginOptions`    | Loads the Intlayer configuration and returns `PurgePluginOptions` ready for use with `intlayerPurgeBabelPlugin`.                                  |
+| `getMinifyPluginOptions`   | Loads the Intlayer configuration and returns `MinifyPluginOptions` ready for use with `intlayerMinifyBabelPlugin`.                                |
+
+---
+
+### Types
+
+| Type                    | Description                                                                                                     |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `CompilerMode`          | Compiler mode: `'dev'` for development with HMR support, or `'build'` for production builds.                    |
+| `ExtractPluginOptions`  | Options for `intlayerExtractBabelPlugin`: files list, configuration, `onExtract` callback, etc.                 |
+| `ExtractResult`         | Extraction result: dictionary key, file path, content, and locale.                                              |
+| `OptimizePluginOptions` | Options for `intlayerOptimizeBabelPlugin`: dictionary paths, import mode, mode map per dictionary, etc.         |
+| `PurgePluginOptions`    | Options for `intlayerPurgeBabelPlugin`: base directory, purge/minify/optimise flags, component files list.      |
+| `MinifyPluginOptions`   | Options for `intlayerMinifyBabelPlugin`: base directory, minify/optimise/editorEnabled flags.                   |
+| `PruneContext`          | Shared state between analysis and pruning plugins: field usage maps, rename maps, etc.                          |
+| `DictionaryFieldUsage`  | Field usage result for a single dictionary: `Set<string>` or `'all'` when static analysis is inconclusive.      |
+| `NestedRenameEntry`     | Node in the rename tree: the shortName and the children map.                                                    |
+| `NestedRenameMap`       | One level in the rename tree: `Map<string, NestedRenameEntry>`.                                                 |
+| `CompatCallerConfig`    | Configuration for a compatible usage analyzer for compat-adapter packages (caller name and processing options). |
+| `ScriptBlock`           | Script block extracted from a SFC file (Vue or Svelte): content, start offset, and end offset.                  |
+
+---
+
+### Utility Functions
+
+| Function                          | Description                                                                                                                                                   |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `generateShortFieldName`          | Converts an integer (starting from zero) into a short alphabetic identifier: `0` → `'a'`, `25` → `'z'`, `26` → `'aa'`, etc.                                   |
+| `buildNestedRenameMapFromContent` | Recursively builds a `NestedRenameMap` from the content value of a compiled dictionary, respecting Intlayer node structures (translation, enumeration, etc.). |
+| `createPruneContext`              | Creates a new empty `PruneContext` object initialized with default values.                                                                                    |
+| `extractScriptBlocks`             | Extracts `<script>` blocks from SFC files (Vue / Svelte) for subsequent Babel analysis.                                                                       |
+| `BABEL_PARSER_OPTIONS`            | Constant representing Babel parser options covering the supported frameworks (React/Vue/Svelte/Angular/...).                                                  |
+| `INTLAYER_CALLER_NAMES`           | Constant list of original Intlayer caller names: `['useIntlayer', 'getIntlayer']`.                                                                            |
+
+---
+
+## Example Usage
+
+```js
+// babel.config.js
+const {
+  intlayerExtractBabelPlugin,
+  intlayerPurgeBabelPlugin,
+  intlayerMinifyBabelPlugin,
+  intlayerOptimizeBabelPlugin,
+  getExtractPluginOptions,
+  getPurgePluginOptions,
+  getMinifyPluginOptions,
+  getOptimizePluginOptions,
+} = require("@intlayer/babel");
+
+module.exports = {
+  presets: ["next/babel"],
+  plugins: [
+    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
+    [intlayerPurgeBabelPlugin, getPurgePluginOptions()],
+    [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],
+    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
+  ],
+};
+```
+
+> **Note:** The `intlayerPurgeBabelPlugin` must be declared **before** `intlayerMinifyBabelPlugin`, because the latter reads the rename map built by the former. In addition, they both must be preceded by `intlayerOptimizeBabelPlugin` so that it can see the dictionary keys before the `useIntlayer` calls are rewritten.

package/docs/en-GB/packages/vite-intlayer/intlayerCompiler.md

@@ -0,0 +1,120 @@
+---
+createdAt: 2026-06-25
+updatedAt: 2026-06-25
+title: intlayerCompiler Vite Plugin Documentation | vite-intlayer
+description: Vite plugin that extracts inline Intlayer content declarations from component files and writes them to dictionary JSON files at build/transform time.
+keywords:
+  - intlayerCompiler
+  - vite
+  - plugin
+  - compiler
+  - content
+  - dictionary
+  - internationalisation
+  - i18n
+slugs:
+  - doc
+  - packages
+  - vite-intlayer
+  - intlayerCompiler
+history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "Bundled into intlayer(); init doc"
+author: aymericzip
+---
+
+# intlayerCompiler
+
+`intlayerCompiler` is a Vite plugin that scans component source files for **inline Intlayer content declarations** — content defined directly inside a component rather than in a separate `.content.ts` file — and writes them to dictionary JSON files during the transform phase.
+
+> **Since Intlayer v9** `intlayerCompiler` is automatically included inside the main [`intlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/vite-intlayer/intlayer.md) plugin when both `compiler.enabled` is `true` and `compiler.output` is set in your Intlayer config. You only need to register it separately when you want full control over compiler-specific configuration.
+
+## Usage
+
+### As part of `intlayer()` (recommended, v9+)
+
+Enable the compiler through your Intlayer config:
+
+```ts
+// intlayer.config.ts
+import { defineConfig } from "intlayer";
+
+export default defineConfig({
+  compiler: {
+    enabled: true,
+    output: "./src/dictionaries", // where extracted dictionaries are written
+  },
+});
+```
+
+Then use the standard plugin with no extra registration:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+### Standalone (when needed)
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayerCompiler } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayerCompiler()],
+});
+```
+
+## Options
+
+```ts
+import type { IntlayerCompilerOptions } from "vite-intlayer";
+```
+
+| Option           | Type                      | Description                                                                                 |
+| ---------------- | ------------------------- | ------------------------------------------------------------------------------------------- |
+| `configOptions`  | `GetConfigurationOptions` | Intlayer configuration overrides forwarded to `getConfiguration()`.                         |
+| `compilerConfig` | `Partial<CompilerConfig>` | Overrides for the compiler-specific config section (e.g. `enabled`, `output`, `filesList`). |
+
+### Example
+
+```ts
+intlayerCompiler({
+  configOptions: { configFile: "./config/intlayer.config.ts" },
+  compilerConfig: { enabled: true, output: "./src/dictionaries" },
+});
+```
+
+## How it works
+
+### Transform phase
+
+For every source file that matches `compiler.filesList`, the compiler plugin:
+
+1. Passes the file content through `extractContent` from `@intlayer/babel`.
+2. Calls `onExtract` for each declaration found, which writes the resulting dictionary JSON to `compiler.output`.
+3. Returns the transformed source code with inline declarations replaced by standard `useIntlayer('key')` / `getIntlayer('key')` calls.
+
+Supported file types: `.ts`, `.tsx`, `.js`, `.jsx`, `.vue`, `.svelte`, `.astro`.
+
+### HMR (Hot Module Replacement)
+
+When a component file is saved in development mode, the compiler:
+
+1. Detects the file change via Vite's `handleHotUpdate` hook.
+2. Re-extracts content from the updated file.
+3. Writes the updated dictionary JSON.
+4. Triggers a full page reload (`server.ws.send({ type: 'full-reload' })`).
+
+A 500 ms debounce prevents the dictionary write itself (which also triggers a file-change event) from causing an infinite re-extraction loop.
+
+### Deduplication
+
+`intlayerCompiler` uses the same `createPrimaryInstanceGuard` deduplication mechanism as the other bundled plugins. When both `intlayer()` (which bundles the compiler) and a manual `intlayerCompiler()` call are present, only the first registered instance runs — no dictionaries are written twice.

package/docs/en-GB/packages/vite-intlayer/intlayerMinify.md

@@ -0,0 +1,92 @@
+---
+createdAt: 2026-06-25
+updatedAt: 2026-06-25
+title: intlayerMinify Vite Plugin Documentation | vite-intlayer
+description: Vite plugin that minifies compiled Intlayer dictionary JSON files and optionally mangles content field names to reduce bundle size.
+keywords:
+  - intlayerMinify
+  - vite
+  - plugin
+  - minify
+  - bundle size
+  - dictionary
+  - internationalisation
+  - i18n
+slugs:
+  - doc
+  - packages
+  - vite-intlayer
+  - intlayerMinify
+history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "Init doc"
+author: aymericzip
+---
+
+# intlayerMinify
+
+`intlayerMinify` is a Vite plugin that minifies compiled dictionary JSON files during a production build. It strips all unnecessary whitespace and, when combined with `intlayerPrune`, optionally renames content field names to short alphabetic aliases (`a`, `b`, `c`, …) to further reduce bundle size.
+
+> The plugin is already included and configured automatically when you use [`intlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/vite-intlayer/intlayer.md). You only need to register it manually if you are composing the plugin stack yourself.
+
+## Usage
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayerMinify, intlayerPrune } from "vite-intlayer";
+import { createPruneContext } from "@intlayer/babel";
+
+const pruneContext = createPruneContext();
+
+export default defineConfig({
+  plugins: [
+    intlayerPrune(intlayerConfig, pruneContext),
+    intlayerMinify(intlayerConfig, pruneContext),
+  ],
+});
+```
+
+## Activation conditions
+
+`intlayerMinify` is active **only** when all three of the following are true:
+
+1. The Vite command is `build` (not `serve` / dev).
+2. `build.optimize` is `true` (or `undefined`, which defaults to `true` for builds).
+3. `build.minify` is `true` in your Intlayer config.
+
+It is automatically **disabled** when `editor.enabled` is `true` because the editor needs the full, human-readable dictionary content.
+
+## What gets minified
+
+The plugin targets two dictionary locations (as resolved from `intlayer.system`):
+
+- `dictionariesDir` — static all-locale dictionaries (e.g. `.intlayer/dictionaries/*.json`)
+- `dynamicDictionariesDir` — per-locale dynamic dictionaries
+
+> Fetch-mode dictionaries (`fetchDictionariesDir`) are **never** minified because they are served from a remote API at runtime using their original field names. Renaming fields would create a mismatch between the server response and client-side property accesses.
+
+## Field-name mangling (property minification)
+
+When `intlayerPrune` has analysed the codebase and populated `pruneContext.dictionaryKeyToFieldRenameMap`, `intlayerMinify` also renames content field names to short aliases. For example:
+
+```json
+// before
+{ "key": "myDict", "content": { "title": "Hello", "description": "World" } }
+
+// after (with mangling)
+{ "key": "myDict", "content": { "a": "Hello", "b": "World" } }
+```
+
+The corresponding source-file property accesses are renamed by the Babel pass inside `intlayerOptimize`, so runtime behaviour is unchanged.
+
+Internal Intlayer fields (`nodeType`, `translation`, etc.) are never renamed.
+
+## Edge-case dictionaries
+
+Dictionaries flagged in `pruneContext.dictionariesWithEdgeCases` (structural anomalies detected during the prune phase) are skipped entirely — neither minified nor mangled — to avoid shipping broken data.
+
+## Qualified groups (collections / variants / meta records)
+
+For dictionaries with a `qualifierTypes` array (collections, variants, and meta records), the plugin preserves the `qualifierTypes` array and the `meta` side-map verbatim. Only the `content` entries have their field names mangled. The composite keys (used for selector matching at runtime) are never touched.