@intlayer/docs 9.1.3 → 9.3.0

package/docs/en/bundle_optimization.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-11-25
-updatedAt: 2026-06-24
+updatedAt: 2026-08-09
 title: Optimizing i18n Bundle Size & Performance
 description: Reduce application bundle size by optimizing internationalization (i18n) content. Learn how to leverage tree shaking and lazy loading for dictionaries with Intlayer.
 keywords:
@@ -16,6 +16,9 @@ slugs:
   - concept
   - bundle-optimization
 history:
+  - version: 9.2.1
+    date: 2026-08-09
+    changes: "`purge` and `minify` now work on Next.js through `@intlayer/swc` — no `babel.config.js` required"
   - version: 8.12.0
     date: 2026-06-24
     changes: "List Babel plugins in required pipeline order (extract → purge → minify → optimize) in the reference tables"
@@ -225,6 +228,20 @@ Vite users **never configure these directly**. They are wired up automatically w
 | Dictionary minify    | Same as `intlayerMinifyBabelPlugin` JSON-write pass                                    |
 | Babel transform      | Same as `intlayerMinifyBabelPlugin` source-code rename + `intlayerOptimizeBabelPlugin` |
 
+### SWC plugin (`@intlayer/swc`)
+
+Next.js users **never configure these directly** either. Since **v9.2.1**, `withIntlayer()` in `next.config.ts` runs the full pipeline — purge, minify and import rewriting — from the `build.purge` and `build.minify` flags alone.
+
+The work is split in two, because an SWC Wasm plugin transforms one file at a time with no file-system access:
+
+| Pass                                      | Where it runs                 | What it does                                                                              |
+| :---------------------------------------- | :---------------------------- | :---------------------------------------------------------------------------------------- |
+| Usage analysis + JSON purge/minify        | Node, inside `withIntlayer()` | Reads every component source file, rewrites `.intlayer/**/*.json`, produces rename tables |
+| Source rewriting (`content.title` → `.a`) | `@intlayer/swc` (Wasm)        | Applies the rename tables to the matching property accesses in your code                  |
+| Import rewriting (`useIntlayer` → dict)   | `@intlayer/swc` (Wasm)        | Same as `intlayerOptimizeBabelPlugin`                                                     |
+
+Deciding _which_ fields are unused and _what_ alias each one gets requires cross-file state and file I/O, so that half runs in Node; the SWC plugin only receives the resulting tables.
+
 ## Setup by Platform
 
 <Tabs>
@@ -232,10 +249,12 @@ Vite users **never configure these directly**. They are wired up automatically w
 
 ### Next.js
 
-Next.js requires the `@intlayer/swc` plugin for the optimize (import rewriting) pass, because Next.js uses SWC for builds.
+Next.js requires the `@intlayer/swc` plugin, because Next.js uses SWC for builds. Since **v9.2.1** this single package covers the whole pipeline — optimize (import rewriting), purge and minify.
 
 > This plugin is not installed by default because SWC plugins are still experimental for Next.js. It may change in the future.
 
+> **Next.js 16.1.0 is the minimum version.** It is the first release built on SWC's forward-compatible Wasm plugin ABI; earlier releases reject the plugin. `withIntlayer` reads your Next.js version and simply does not register the plugin below 16.1.0 — those builds still succeed, they just run without bundle optimization.
+
 <Tabs>
  <Tab value="npm">
 
@@ -270,33 +289,40 @@ intlayer-swc-plugin = "*"
 
 Once installed, Intlayer will automatically detect and use the plugin.
 
-For the **purge and minify** passes (field removal and field renaming), install `@intlayer/babel` alongside and add the Babel plugins. Because Next.js uses SWC for transform but still evaluates `babel.config.js` for plugin configuration, the Babel plugins run as a pre-pass before SWC.
+The **purge and minify** passes (field removal and field renaming) require no extra package and no `babel.config.js`. Wrap your config with `withIntlayer` and toggle the flags in `intlayer.config.ts`:
 
-```bash packageManager="npm"
-npm install -D @intlayer/babel
+```typescript fileName="next.config.ts"
+import { withIntlayer } from "next-intlayer/server";
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {/* your config */};
+
+export default withIntlayer(nextConfig);
 ```
 
-```javascript fileName="babel.config.js"
-const {
-  intlayerPurgeBabelPlugin,
-  intlayerMinifyBabelPlugin,
-  getPurgePluginOptions,
-  getMinifyPluginOptions,
-} = require("@intlayer/babel");
+```typescript fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
 
-module.exports = {
-  presets: ["next/babel"],
-  plugins: [
-    // Purge: remove unused content fields from .intlayer/**/*.json
-    [intlayerPurgeBabelPlugin, getPurgePluginOptions()],
-    // Minify: rename content field keys in JSON + source code
-    [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],
-    // Note: intlayerOptimizeBabelPlugin is NOT needed here because
-    // @intlayer/swc handles the useIntlayer → useDictionary rewrite.
-  ],
+const config: IntlayerConfig = {
+  build: {
+    purge: true, // remove unused content fields from bundled JSON
+    minify: true, // rename content field keys to short aliases
+  },
 };
+
+export default config;
 ```
 
+During `next build`, `withIntlayer` analyzes your sources, rewrites the compiled dictionaries, and forwards the resulting field-rename tables to `@intlayer/swc`, which updates the matching property accesses in your code.
+
+> Use the async `withIntlayer`, not `withIntlayerSync`. The sync variant does not run the analysis pipeline, so purge and minify have no effect with it.
+
+> Purge and minify run on `next build` only — the optimize pipeline is off during `next dev`.
+
+> They are also disabled when compat-adapter callers are configured (`swcExtraCallers`, set by the compat packages such as `@intlayer/next-intl` or `@intlayer/react-i18next`): those call sites are invisible to the usage analyzer, so purging would remove fields the code still reads. Import rewriting stays active.
+
+**Earlier versions (before 9.2.1)** required `@intlayer/babel` and a `babel.config.js` declaring `intlayerPurgeBabelPlugin` and `intlayerMinifyBabelPlugin`. That file is no longer needed and can be deleted.
+
  </Tab>
  <Tab value="vite">
 
@@ -452,6 +478,8 @@ export default config;
 
 > Minification is skipped when `optimize` is `false` or when `editor.enabled` is `true` (the visual editor requires the original field names to allow editing).
 
+> On Next.js, minification is also skipped when `@intlayer/swc` is not installed or cannot be loaded (Next.js below 16.1.0). The plugin is the half that rewrites the source accesses, so renaming the dictionaries without it would leave your code reading field names that no longer exist.
+
 > Minification is also skipped for dictionaries loaded via `importMode: 'fetch'` because their JSON is served from a remote API using the original field names — renaming the client-side keys would break the server/client contract.
 
 ### Purging (unused field removal)
@@ -480,7 +508,7 @@ export default config;
 { "title": "…", "subtitle": "…" }
 ```
 
-> Purge is skipped when `optimize` is `false` or when `editor.enabled` is `true`.
+> Purge is skipped when `optimize` is `false` or when `editor.enabled` is `true`. On Next.js it is additionally skipped when `@intlayer/swc` is unavailable, and when compat-adapter callers are configured.
 
 > Purge is also skipped conservatively when a source file cannot be parsed, or when the result of `useIntlayer` is assigned to a variable and passed around in ways the static analyser cannot follow (e.g. spread into an object, passed as a prop without destructuring). In those cases the full dictionary is kept.
 

package/docs/en/cli/doc-review.md

@@ -16,6 +16,9 @@ slugs:
   - cli
   - doc-review
 history:
+  - version: 9.0.0
+    date: 2026-08-06
+    changes: "Replace --log by --mode and log a synthesis at the end of the run"
   - version: 9.0.0
     date: 2026-06-17
     changes: "Add --log option"
@@ -89,9 +92,17 @@ For most use cases,
 
 **Review mode options:**
 
-- **`--log`**: Log-only mode. Do not translate with AI; instead log the blocks that need attention (with line numbers and content) for the base and target locales, to help another agent generate the translations.
+- **`--mode [mode]`**: How the review runs. Defaults to `apply`.
+
+  - `apply`: translate the diverging blocks with AI and write the files.
+  - `report`: do not call any AI; log the blocks that need attention (with line numbers and content) for the base and target locales, to help another agent generate the translations.
+  - `synthesis`: do not call any AI and skip the per-block output; only log the final recap of the documents that are up to date and the ones that have blocks to edit.
+
+  > Example: `npx intlayer doc review --mode report`
+
+  > Example: `npx intlayer doc review --mode synthesis`
 
-  > Example: `npx intlayer doc review --log`
+Whatever the mode, the run ends with a synthesis listing the documents that are aligned with their base document and the ones that still have blocks to edit.
 
 **Entry output options:**
 

package/docs/en/configuration.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-07-11
+updatedAt: 2026-08-06
 title: Configuration
 description: Learn how to configure Intlayer for your application. Understand the various settings and options available to customize Intlayer to your needs.
 keywords:
@@ -14,6 +14,9 @@ slugs:
   - concept
   - configuration
 history:
+  - version: 9.1.3
+    date: 2026-08-06
+    changes: "Make `routing.enableProxy` tri-state: unset (auto), `true`, `false`"
   - version: 9.0.0
     date: 2026-07-11
     changes: "Add `analytics` configuration"
@@ -237,13 +240,19 @@ const config: IntlayerConfig = {
 
     /**
      * Enables the Intlayer locale-routing proxy (middleware).
-     * When enabled, the build-tool integration (e.g. the `intlayer()` Vite plugin)
-     * automatically wires the locale detection / redirect / rewrite middleware in
-     * development, preview and production SSR. On Next.js, the `intlayerProxy`
-     * middleware becomes a pass-through when disabled.
-     * Default: true
+     * The build-tool integration (e.g. the `intlayer()` Vite plugin) wires the
+     * locale detection / redirect / rewrite middleware in development, preview
+     * and production SSR.
+     * - unset (auto): the proxy runs, but development and preview servers keep
+     *   locale routing URL-driven by ignoring the locale stored in cookies and
+     *   headers. Locale prefixes still resolve, the locale is still persisted,
+     *   and Accept-Language detection still applies. Production behaves like `true`.
+     * - true: full behaviour in every environment, storage-driven redirects included.
+     * - false: no locale routing. On Next.js, the `intlayerProxy` middleware
+     *   becomes a pass-through.
+     * Default: undefined (auto)
      */
-    enableProxy: true,
+    enableProxy: undefined,
 
     /**
      * Where to store the user's selected locale.
@@ -725,14 +734,14 @@ Analytics is strictly opt-in: nothing is collected unless `analytics.enabled` is
 
 Settings that control routing behavior, including URL structure, locale storage, and middleware handling.
 
-| Field         | Description                                                                                                                                                                  | Type                                                                                                                                                                                                         | Default                | Example                                                                                                                                                                                     | Note                                                                                                                                                                                                                                                                                                                                 |
-| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `mode`        | URL routing mode for locale handling.                                                                                                                                        | `'prefix-no-default'` &#124; <br/> `'prefix-all'` &#124; <br/> `'no-prefix'` &#124; <br/> `'search-params'`                                                                                                  | `'prefix-no-default'`  | `'prefix-no-default'`: `/dashboard` (en) or `/fr/dashboard` (fr). `'prefix-all'`: `/en/dashboard`. `'no-prefix'`: locale handled via other means. `'search-params'`: `/dashboard?locale=fr` | Does not impact cookie or locale storage management.                                                                                                                                                                                                                                                                                 |
-| `enableProxy` | Enables the Intlayer locale-routing proxy (middleware).                                                                                                                      | `boolean`                                                                                                                                                                                                    | `true`                 | `false`                                                                                                                                                                                     | When enabled, the build-tool integration (e.g. the `intlayer()` Vite plugin) automatically wires the locale detection / redirect / rewrite middleware in development, preview and production SSR. On Next.js, the `intlayerProxy` middleware becomes a pass-through when disabled. Set to `false` to handle locale routing yourself. |
-| `storage`     | Configuration for storing the locale in the client.                                                                                                                          | `false` &#124; <br/> `'cookie'` &#124; <br/> `'localStorage'` &#124; <br/> `'sessionStorage'` &#124; <br/> `'header'` &#124; <br/> `CookiesAttributes` &#124; <br/> `StorageAttributes` &#124; <br/> `Array` | `['cookie', 'header']` | `'localStorage'` <br/> `[{ type: 'cookie', name: 'custom-locale', secure: true }]`                                                                                                          | See Storage Options table below.                                                                                                                                                                                                                                                                                                     |
-| `basePath`    | The base path for the application URLs.                                                                                                                                      | `string`                                                                                                                                                                                                     | `''`                   | `'/my-app'`                                                                                                                                                                                 | If app is at `https://example.com/my-app, basePath is `'/my-app'`and URLs become`https://example.com/my-app/en`.                                                                                                                                                                                                                     |
-| `rewrite`     | Custom URL rewriting rules that override the default routing mode for specific paths. Supports `[param]` dynamic parameters.                                                 | `Record<string, StrictModeLocaleMap<string>>`                                                                                                                                                                | `undefined`            | See example below                                                                                                                                                                           | • Rewrite rules take precedence over `mode`.<br/>• Works with Next.js and Vite.<br/>• `getLocalizedUrl()` automatically applies matching rules.<br/>• See [Custom URL Rewrites](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/custom_url_rewrites.md).                                                               |
-| `domains`     | Maps locales to domain hostnames for domain-based routing. When set, URLs for a locale use that domain as the base (absolute URL) and no locale prefix is added to the path. | `Partial<Record<Locale, string>>`                                                                                                                                                                            | `undefined`            | `{ zh: 'intlayer.zh', fr: 'intlayer.org' }`                                                                                                                                                 | • Protocol defaults to `https://` when not included in the hostname.<br/>• The domain itself identifies the locale, so no `/zh/` prefix is added.<br/>• `getLocalizedUrl('/', 'zh')` returns `https://intlayer.zh/`.                                                                                                                 |
+| Field         | Description                                                                                                                                                                  | Type                                                                                                                                                                                                         | Default                | Example                                                                                                                                                                                     | Note                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mode`        | URL routing mode for locale handling.                                                                                                                                        | `'prefix-no-default'` &#124; <br/> `'prefix-all'` &#124; <br/> `'no-prefix'` &#124; <br/> `'search-params'`                                                                                                  | `'prefix-no-default'`  | `'prefix-no-default'`: `/dashboard` (en) or `/fr/dashboard` (fr). `'prefix-all'`: `/en/dashboard`. `'no-prefix'`: locale handled via other means. `'search-params'`: `/dashboard?locale=fr` | Does not impact cookie or locale storage management.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `enableProxy` | Enables the Intlayer locale-routing proxy (middleware).                                                                                                                      | `boolean` &#124; <br/> `undefined`                                                                                                                                                                           | `undefined` (auto)     | `true`                                                                                                                                                                                      | • Unset (auto): the proxy runs, but development and preview servers ignore the locale stored in cookies/headers as a redirect source. Locale prefixes still resolve (`/en` → `/`), the locale is still persisted, and `Accept-Language` detection still applies. Production behaves like `true`.<br/>• `true`: full behaviour in every environment, storage-driven redirects included.<br/>• `false`: no locale routing; handle it yourself. On Next.js, the `intlayerProxy` middleware becomes a pass-through. |
+| `storage`     | Configuration for storing the locale in the client.                                                                                                                          | `false` &#124; <br/> `'cookie'` &#124; <br/> `'localStorage'` &#124; <br/> `'sessionStorage'` &#124; <br/> `'header'` &#124; <br/> `CookiesAttributes` &#124; <br/> `StorageAttributes` &#124; <br/> `Array` | `['cookie', 'header']` | `'localStorage'` <br/> `[{ type: 'cookie', name: 'custom-locale', secure: true }]`                                                                                                          | See Storage Options table below.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `basePath`    | The base path for the application URLs.                                                                                                                                      | `string`                                                                                                                                                                                                     | `''`                   | `'/my-app'`                                                                                                                                                                                 | If app is at `https://example.com/my-app, basePath is `'/my-app'`and URLs become`https://example.com/my-app/en`.                                                                                                                                                                                                                                                                                                                                                                                                |
+| `rewrite`     | Custom URL rewriting rules that override the default routing mode for specific paths. Supports `[param]` dynamic parameters.                                                 | `Record<string, StrictModeLocaleMap<string>>`                                                                                                                                                                | `undefined`            | See example below                                                                                                                                                                           | • Rewrite rules take precedence over `mode`.<br/>• Works with Next.js and Vite.<br/>• `getLocalizedUrl()` automatically applies matching rules.<br/>• See [Custom URL Rewrites](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/custom_url_rewrites.md).                                                                                                                                                                                                                                          |
+| `domains`     | Maps locales to domain hostnames for domain-based routing. When set, URLs for a locale use that domain as the base (absolute URL) and no locale prefix is added to the path. | `Partial<Record<Locale, string>>`                                                                                                                                                                            | `undefined`            | `{ zh: 'intlayer.zh', fr: 'intlayer.org' }`                                                                                                                                                 | • Protocol defaults to `https://` when not included in the hostname.<br/>• The domain itself identifies the locale, so no `/zh/` prefix is added.<br/>• `getLocalizedUrl('/', 'zh')` returns `https://intlayer.zh/`.                                                                                                                                                                                                                                                                                            |
 
 **`rewrite` example**:
 

package/docs/en/intlayer_with_angular_21.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2025-04-18
 updatedAt: 2026-05-31
-title: "Angular 21 i18n - Complete guide to translate your app"
-description: "No more i18next. The 2026 guide to building a multilingual (i18n) Angular 21 app. Translate with AI agents and optimize bundle size, SEO and performances."
+title: "Angular 22 i18n - Complete guide to translate your app"
+description: "No more i18next. The 2026 guide to building a multilingual (i18n) Angular 22 app. Translate with AI agents and optimize bundle size, SEO and performances."
 keywords:
   - Internationalization
   - Documentation
@@ -13,8 +13,8 @@ slugs:
   - doc
   - environment
   - angular
-applicationTemplate: https://github.com/aymericzip/intlayer-angular-21-template
-applicationShowcase: https://intlayer-angular-21-template.vercel.app/
+applicationTemplate: https://github.com/aymericzip/intlayer-angular-22-template
+applicationShowcase: https://intlayer-angular-22-template.vercel.app/
 history:
   - version: 8.9.0
     date: 2026-05-04
@@ -31,7 +31,7 @@ history:
 author: aymericzip
 ---
 
-# Translate your Angular 21 (Vite) website using Intlayer | Internationalization (i18n)
+# Translate your Angular 22 (Vite) website using Intlayer | Internationalization (i18n)
 
 ## Table of Contents
 
@@ -94,7 +94,7 @@ More than just an i18n solution, Intlayer provides an **self-hosted [visual edit
   <Tab label="Code" value="code">
 
 <iframe
-  src="https://ide.intlayer.org/aymericzip/intlayer-angular-21-template?file=intlayer.config.ts"
+  src="https://ide.intlayer.org/aymericzip/intlayer-angular-22-template?file=intlayer.config.ts"
   className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
   title="Demo CodeSandbox - How to Internationalize your application using Intlayer"
   sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
@@ -105,7 +105,7 @@ More than just an i18n solution, Intlayer provides an **self-hosted [visual edit
   <Tab label="Demo" value="demo">
 
 <iframe
-  src="https://intlayer-angular-21-template.vercel.app/"
+  src="https://intlayer-angular-22-template.vercel.app/"
   className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
   title="Demo - intlayer-angular-template"
   sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
@@ -115,7 +115,7 @@ More than just an i18n solution, Intlayer provides an **self-hosted [visual edit
   </Tab>
 </Tabs>
 
-See [Application Template](https://github.com/aymericzip/intlayer-angular-21-template) on GitHub.
+See [Application Template](https://github.com/aymericzip/intlayer-angular-22-template) on GitHub.
 
 <Steps>
 
@@ -203,7 +203,7 @@ export default config;
 
 <Step number={3} title="Integrate Intlayer in Your Angular Configuration">
 
-To integrate Intlayer with the Angular CLI, you need to use a custom builder. This guide assumes you are using Vite/esbuild (default for Angular 21 projects).
+To integrate Intlayer with the Angular CLI, you need to use a custom builder. This guide assumes you are using Vite/esbuild (default for Angular 22 projects).
 
 First, modify your `angular.json` to use the custom esbuild builder. Update the `build` and `serve` configurations: