@intlayer/docs 9.1.3 → 9.3.0

package/docs/en/intlayer_with_vite+solid.md

@@ -15,6 +15,7 @@ slugs:
   - environment
   - vite-and-solid
 applicationTemplate: https://github.com/aymericzip/intlayer-vite-solid-template
+applicationShowcase: https://intlayer-vite-solid.vercel.app
 history:
   - version: 8.9.0
     date: 2026-05-04
@@ -46,6 +47,17 @@ author: aymericzip
   loading="lazy"
 />
 
+  </Tab>
+  <Tab label="Demo" value="demo">
+
+<iframe
+  src="https://intlayer-vite-solid.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 Vite + Solid Template"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
+
   </Tab>
 </Tabs>
 

package/docs/en/live-sync.md

@@ -12,6 +12,10 @@ keywords:
   - Intlayer
   - Next.js
   - Vite
+slugs:
+  - doc
+  - concept
+  - live-sync
 history:
   - version: 9.0.0
     date: 2026-07-08

package/docs/en-GB/analytics.md

@@ -0,0 +1,222 @@
+---
+createdAt: 2026-07-08
+updatedAt: 2026-07-08
+title: Intlayer Analytics | Track content exposure and run A/B tests
+description: Discover how @intlayer/analytics tracks page/locale views and content exposure, and how to use it to run A/B tests on your Intlayer content.
+keywords:
+  - Analytics
+  - A/B Testing
+  - Audience
+  - Internationalisation
+  - Documentation
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - analytics
+history:
+  - version: 9.0.0
+    date: 2026-07-08
+    changes: "Init doc — @intlayer/analytics package, provider/node-level tracking, A/B testing, dashboard"
+author: aymericzip
+---
+
+# Intlayer Analytics Documentation
+
+`@intlayer/analytics` is an optional companion package that tells you **which content is actually shown** to your visitors — which page, in which locale, and which specific piece of translated content — so you can understand your audience and run **A/B tests on content**.
+
+## Table of Contents
+
+<TOC/>
+
+---
+
+## What it tracks
+
+`@intlayer/analytics` batches three kinds of anonymous events:
+
+| Event              | Captured where                                   | What it tells you                                                                                                         |
+| ------------------ | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| `page_view`        | Provider level (`IntlayerProvider`)              | Which page and locale a session viewed, on first load, route change, or locale switch.                                    |
+| `content_exposure` | Node level (`useIntlayer` / interpreter plugins) | Which dictionary key / key path was actually resolved and displayed — and, when part of an experiment, which **variant**. |
+| `conversion`       | Wherever you call `useConversion()`              | A goal reached (signup, click, purchase…) attributed to the A/B variant the session was exposed to.                       |
+
+Events are collected in memory and sent as a **single batched request roughly every 20 seconds** — never on every keystroke or render — so analytics never impacts first render time or adds a request per interaction.
+
+## How it powers A/B testing on content
+
+Intlayer already lets you declare content [Variants](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dynamic_dictionaries/index.md) (e.g. a `hero-banner` dictionary with a `control` and a `black_friday` variant). `@intlayer/analytics` closes the loop:
+
+1. `getVariant(experimentKey, variants)` deterministically assigns each anonymous session to a variant — a pure function of the session id and the experiment key, so the assignment is **stable across the session** and requires **no server round-trip** before first render (no flicker, no layout shift).
+2. Every `content_exposure` event carries the `variant` that was shown.
+3. `useConversion()` lets you attribute a goal (e.g. `"cta_click"`) to that variant.
+4. The dashboard's experiment results endpoint compares conversion rates per variant, including statistical significance (a z-test).
+
+## Installation
+
+`@intlayer/analytics` is a **peer, optional** dependency — never installed automatically by a framework package. Add it alongside `intlayer`:
+
+```bash packageManager="npm"
+npm install @intlayer/analytics
+```
+
+```bash packageManager="yarn"
+yarn add @intlayer/analytics
+```
+
+```bash packageManager="pnpm"
+pnpm add @intlayer/analytics
+```
+
+```bash packageManager="bun"
+bun add @intlayer/analytics
+```
+
+If you don't install it, every integration point resolves to a no-op — see [Zero-cost when not installed](#zero-cost-when-not-installed) below.
+
+## Configuration
+
+Analytics **reuses the existing `editor` configuration block** — there is no separate `analytics` config schema to fill in:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  editor: {
+    backendURL: "https://back.intlayer.org", // Also used as the analytics ingestion endpoint
+    clientId: "your-client-id", // Also used as the analytics project key
+    clientSecret: "your-client-secret",
+  },
+};
+
+export default config;
+```
+
+- `editor.backendURL` — the base URL analytics events are sent to (`POST {backendURL}/api/analytics/events`).
+- `editor.clientId` — the public project key attributed to every ingested event. It also acts as the **enable switch**: analytics stays fully disabled (and tree-shaken, see below) until `clientId` is configured.
+
+If you self-host Intlayer, analytics automatically points at your own instance since it shares `editor.backendURL`.
+
+## Framework support
+
+Analytics is wired into the shared `IntlayerProvider` from `react-intlayer`, so it is available today anywhere that provider is used:
+
+| Framework                                                | Status                                                                                             |
+| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| React                                                    | ✅ Available                                                                                       |
+| Next.js (`next-intlayer`)                                | ✅ Available (via `react-intlayer`)                                                                |
+| React Native / Expo (`react-native-intlayer`)            | ✅ Available (via `react-intlayer`)                                                                |
+| Vue, Svelte, Angular, Solid, Preact, Lit, Astro, Vanilla | 🚧 Planned — same client, provider-level bindings following the `@intlayer/editor` rollout pattern |
+
+## Usage
+
+### Automatic provider-level tracking
+
+No code changes are required. Once `@intlayer/analytics` is installed and `editor.clientId` is configured, `IntlayerProvider` automatically:
+
+- initialises the analytics client on mount,
+- records a `page_view` on initial load,
+- records a `page_view` on every locale change,
+- starts the ~20s flush loop and flushes any remaining events on unmount / tab close (via `navigator.sendBeacon`, falling back to `fetch(..., { keepalive: true })`).
+
+### Automatic node-level tracking
+
+Every time `useIntlayer` resolves a piece of content for display, the interpreter reports a `content_exposure` event for that exact `dictionaryKey` + key path + locale — again, no code changes required. Repeated exposures of the same node within a flush window are coalesced into a single event with a `count`, so a list re-rendering 50 times doesn't send 50 events.
+
+### Tracking conversions for A/B tests
+
+Use `useConversion()` to attribute a goal to the variant a session saw:
+
+```tsx fileName="CTAButton.tsx" codeFormat="tsx"
+import { useConversion } from "react-intlayer";
+
+const CTAButton = () => {
+  const trackConversion = useConversion();
+
+  return (
+    <button
+      onClick={() =>
+        trackConversion({
+          experimentKey: "homepage-hero",
+          variant: "black_friday",
+          goal: "cta_click",
+        })
+      }
+    >
+      Get started
+    </button>
+  );
+};
+```
+
+### Resolving a variant client-side
+
+```tsx fileName="useHeroVariant.ts" codeFormat="tsx"
+import { getGlobalAnalyticsClient } from "@intlayer/analytics/client";
+
+const client = getGlobalAnalyticsClient();
+const variant = client?.getVariant("homepage-hero", [
+  "control",
+  "black_friday",
+]);
+```
+
+## Privacy & performance
+
+- **Anonymous by design**: sessions are identified by a rotating id; the backend only ever stores a **SHA-256 hash** of that id — never the raw id, never an IP address.
+- **Location is coarse**: only a country code, derived from CDN geolocation headers (`cf-ipcountry`, `x-vercel-ip-country`, …) — no IP is read or stored.
+- **URLs exclude search params** by default, so query strings are never captured.
+- **Sampling**: `sampleRate` lets you keep only a fraction of content-exposure events on high-traffic apps.
+- **Batched**: one request roughly every 20 seconds (`flushInterval`), or earlier if the buffer fills up (`maxBufferSize`) — never one request per event.
+
+### Zero-cost when not installed
+
+`@intlayer/analytics` follows the exact same optional-dependency pattern as `@intlayer/editor`:
+
+- every integration point loads the package via a **dynamic `import()` wrapped in `try/catch`** — an app that never installs `@intlayer/analytics` never pays a bundle-size or runtime cost, and never sees an error;
+- a compile-time env var (`INTLAYER_ANALYTICS_ENABLED`), automatically set to `'false'` by `@intlayer/config` whenever `editor.clientId` is not configured, lets bundlers **dead-code-eliminate** the whole integration;
+- analytics is disabled inside the Intlayer editor/CMS preview iframe, so editor sessions are never counted as real traffic.
+
+## Dashboard: Analytics page
+
+Once your project has collected events, the **Analytics** page in the [Intlayer dashboard](https://app.intlayer.org/analytics) (visible in the sidebar once a project is selected) shows:
+
+- **Active users** — distinct visitors over the selected rolling window (7 / 30 / 90 days).
+- **Users today** and **users over the last 7 days**.
+- **Page views** over the selected window.
+- An **evolution graph** of daily distinct visitors.
+- **Locales** and **Location** breakdown tabs, ranking your audience by locale and by country.
+
+## Backend API reference
+
+All read endpoints require authentication; ingestion is public and attributed by `clientId`.
+
+| Method | Endpoint                                    | Description                                                                      |
+| ------ | ------------------------------------------- | -------------------------------------------------------------------------------- |
+| `POST` | `/api/analytics/events`                     | Ingest a batch of events (public, attributed by `clientId` in the body).         |
+| `GET`  | `/api/analytics/overview`                   | Page/locale totals for the authenticated project.                                |
+| `GET`  | `/api/analytics/audience?days=30`           | Distinct visitors, page views, daily series, locale + country breakdowns.        |
+| `GET`  | `/api/analytics/content-stats`              | Per-content exposure totals, grouped by dictionary key / key path / locale.      |
+| `GET`  | `/api/analytics/experiments/:experimentKey` | Per-variant conversion rates and statistical significance for an A/B experiment. |
+
+You can also call these programmatically with the [CMS SDK](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_CMS.md):
+
+```ts fileName="analytics.ts"
+import { createIntlayerCMS } from "@intlayer/api";
+import { analyticsEndpoint } from "@intlayer/api/analytics";
+
+const cms = createIntlayerCMS();
+
+const { data: audience } = await analyticsEndpoint(cms).getAudience(30);
+```
+
+## Useful links
+
+- [Dynamic Dictionaries - Collections & Variants](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dynamic_dictionaries/index.md)
+- [Intlayer CMS - CMS SDK](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_CMS.md)
+- [Intlayer Visual Editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_visual_editor.md)
+- [Configuration Reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md)
+- [Self-Hosting Guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/self_hosting.md)

package/docs/en-GB/autoFill.md

@@ -75,11 +75,30 @@ In v7, the `fill` command behaviour has been updated:
 
 When using a path option to write to another file, the fill mechanism works through a _master-slave_ relationship between content declaration files. The main (master) file serves as the source of truth, and when it's updated, Intlayer will automatically apply those changes to the derived (filled) declaration files specified by the path.
 
-# Autofill Content Declaration File Translations
+### Per-Locale Customisation
 
-**Autofill content declaration files** are a way to speed up your development workflow.
+You can also customise the behaviour for each locale by using an object:
 
-The autofill mechanism works through a _master-slave_ relationship between content declaration files. When the main (master) file is updated, Intlayer will automatically apply those changes to the derived (autofilled) declaration files.
+```ts fileName="intlayer.config.ts"
+const config: IntlayerConfig = {
+  content: {
+    internationalization: {
+      locales: [Locales.ENGLISH, Locales.FRENCH, Locales.POLISH],
+      defaultLocale: Locales.ENGLISH,
+      requiredLocales: [Locales.ENGLISH], // Recommended to avoid Property 'pl' is missing in type '{ en: string; xxx } on your t function if
+    },
+  },
+  dictionary: {
+    fill: {
+      en: true, // Fill and edit the current file for English
+      fr: "./translations/fr.json", // Create separate file for French
+      es: false, // Disable fill for Spanish
+    },
+  },
+};
+```
+
+This allows you to have different fill behaviours for different locales within the same project.
 
 ```ts fileName="src/components/example/example.content.ts"
 import { Locales, type Dictionary } from "intlayer";
@@ -87,7 +106,7 @@ import { Locales, type Dictionary } from "intlayer";
 const exampleContent = {
   key: "example",
   locale: Locales.ENGLISH,
-  autoFill: "./example.content.json",
+  fill: "./example.content.json",
   content: {
     contentExample: "This is an example of content",
   },
@@ -96,7 +115,7 @@ const exampleContent = {
 export default exampleContent;
 ```
 
-Here is a [per-locale content declaration file](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/per_locale_file.md) using the `autoFill` instruction.
+Here is a [per-locale content declaration file](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/per_locale_file.md) using the `fill` instruction.
 
 Then, when you run the following command:
 
@@ -126,14 +145,14 @@ Intlayer will automatically generate the derived declaration file at `src/compon
       "nodeType": "translation",
       "translation": {
         "fr": "Ceci est un exemple de contenu",
-        "es": "Este es un exemple de contenu",
+        "es": "Este es un ejemplo de contenido",
       },
     },
   },
 }
 ```
 
-Afterwards, both declaration files will be merged into a single dictionary, accessible using the standard `useIntlayer("example")` hook (React) / composable (Vue).
+Afterwards, both declaration files will be merged into a single dictionary, accessible using the standard `useIntlayer("example")` hook (react) / composable (vue).
 
 ## Global Configuration
 

package/docs/en-GB/bundle_optimization.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-11-25
-updatedAt: 2026-06-07
+updatedAt: 2026-08-09
 title: i18n Bundle Size & Performance Optimisation
 description: Reduce your application bundle size by optimising internationalisation (i18n) content. Learn how to leverage tree shaking and lazy loading for dictionaries with Intlayer.
 keywords:
@@ -16,6 +16,12 @@ 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"
   - version: 8.12.0
     date: 2026-06-07
     changes: "Added `intlayerPurgeBabelPlugin` and `intlayerMinifyBabelPlugin` for Babel/Webpack; clarified the plugin pipeline"
@@ -191,12 +197,14 @@ Intlayer's build optimisation is split into several discrete plugins, each with
 
 These are used directly in `babel.config.js` for Webpack-based setups (Next.js with Babel, CRA, custom Webpack, etc).
 
+The table below lists them in their required pipeline order (the same order they must appear in `babel.config.js`):
+
 | Plugin                        | What it does                                                                                                        |
 | :---------------------------- | :------------------------------------------------------------------------------------------------------------------ |
 | `intlayerExtractBabelPlugin`  | Scans `.content.ts` files and writes compiled dictionaries to `.intlayer/`                                          |
-| `intlayerOptimizeBabelPlugin` | Rewrites `useIntlayer('key')` → `useDictionary(hash)` and injects the matching dictionary `import`                  |
 | `intlayerPurgeBabelPlugin`    | Scans all source files, removes **unused content fields** from the compiled `.intlayer/**/*.json` dictionary files  |
 | `intlayerMinifyBabelPlugin`   | **Renames content field keys** to short alphabetical aliases (`title` → `a`) in both JSON files and the source code |
+| `intlayerOptimizeBabelPlugin` | Rewrites `useIntlayer('key')` → `useDictionary(hash)` and injects the matching dictionary `import`                  |
 
 > **Plugin order matters.** In your `babel.config.js` the purge and minify plugins must appear **before** the optimize plugin. The optimize pass replaces `useIntlayer('key')` with an opaque `useDictionary(hash)` call, wiping out the dictionary key information the purge and minify passes need to identify which fields are used.
 
@@ -205,9 +213,9 @@ Each Babel plugin has a corresponding options helper that reads your `intlayer.c
 | Options helper               | Used with                     |
 | :--------------------------- | :---------------------------- |
 | `getExtractPluginOptions()`  | `intlayerExtractBabelPlugin`  |
-| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin` |
 | `getPurgePluginOptions()`    | `intlayerPurgeBabelPlugin`    |
 | `getMinifyPluginOptions()`   | `intlayerMinifyBabelPlugin`   |
+| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin` |
 
 ### Vite plugins (`vite-intlayer`)
 
@@ -220,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>
@@ -227,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 optimise (import rewrite) 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 — optimise (import rewriting), purge and minify.
 
 > This plugin is not installed by default as SWC plugins are still experimental for Next.js. This 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 optimisation.
+
 <Tabs>
  <Tab value="npm">
 
@@ -265,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 rename), install `@intlayer/babel` alongside it and add the Babel plugins. Because Next.js uses SWC for transformation but still evaluates `babel.config.js` for plugin config, 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` analyses 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 optimise 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 analyser, 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">
 
@@ -447,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)
@@ -475,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 conservatively skipped 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 track (e.g. spread into an object, passed as a prop without destructuring). In those cases, the full dictionary is preserved.
 

package/docs/en-GB/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"
@@ -235,6 +238,19 @@ const config: IntlayerConfig = {
      */
     mode: "prefix-no-default",
 
+    /**
+     * Enables the Intlayer locale-routing proxy (middleware).
+     * Handles locale detection, redirects and rewrites in dev, preview and SSR.
+     * - unset (auto): development and preview servers keep locale routing
+     *   URL-driven by ignoring the locale stored in cookies and headers.
+     *   Prefixes still resolve, the locale is still persisted, and
+     *   Accept-Language detection still applies. Production behaves like `true`.
+     * - true: full behaviour in every environment.
+     * - false: no locale routing.
+     * Default: undefined (auto)
+     */
+    enableProxy: undefined,
+
     /**
      * Where to store the user's selected locale.
      * Options: 'cookie', 'localStorage', 'sessionStorage', 'header', or an array of these.
@@ -715,13 +731,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.                                                                                                                                                                                                                   |
-| `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 that locale use this domain as a base (absolute URL) and no locale prefix is added to the path. | `Partial<Record<Locale, string>>`                                                                                                                                                                            | `undefined`            | `{ zh: 'intlayer.zh', fr: 'intlayer.org' }`                                                                                                                                                 | • Default protocol is `https://` if 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): development and preview servers ignore the locale stored in cookies/headers as a redirect source; prefixes, persistence and `Accept-Language` detection still apply. Production behaves like `true`.<br/>• `true`: full behaviour everywhere.<br/>• `false`: no locale routing. 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 that locale use this domain as a base (absolute URL) and no locale prefix is added to the path. | `Partial<Record<Locale, string>>`                                                                                                                                                                            | `undefined`            | `{ zh: 'intlayer.zh', fr: 'intlayer.org' }`                                                                                                                                                 | • Default protocol is `https://` if 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-GB/dictionary/file.md

@@ -25,6 +25,8 @@ author: aymericzip
 
 # File Content / Embedding Files in Intlayer
 
+In Intlayer, the `file` function allows embedding external file content into a dictionary. This approach ensures that Intlayer recognises the source file, enabling seamless integration with the Intlayer Visual Editor and CMS.
+
 ## How File Embedding Works
 
 <Tabs group="framework">