@intlayer/docs 9.1.3 → 9.2.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-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/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">