@intlayer/docs 9.0.0-canary.8 → 9.0.0

package/docs/en/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
+  - Internationalization
+  - 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/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:
+
+- initializes 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/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/dynamic_dictionaries/index.md)
+- [Intlayer CMS - CMS SDK](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)
+- [Intlayer Visual Editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md)
+- [Configuration Reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md)
+- [Self-Hosting Guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/self_hosting.md)

package/docs/en/bundle_optimization.md

@@ -236,6 +236,9 @@ Next.js requires the `@intlayer/swc` plugin for the optimize (import rewriting)
 
 > This plugin is not installed by default because SWC plugins are still experimental for Next.js. It may change in the future.
 
+<Tabs>
+ <Tab value="npm">
+
 ```bash packageManager="npm"
 npm install -D @intlayer/swc
 ```
@@ -252,6 +255,19 @@ pnpm add -D @intlayer/swc
 bun add -d @intlayer/swc
 ```
 
+ </Tab>
+ <Tab value="Crates.io (rust)">
+
+```toml fileName="Cargo.toml"
+[dependencies]
+intlayer-swc-plugin = "*"
+```
+
+[View on Crates.io](https://crates.io/crates/intlayer-swc-plugin)
+
+ </Tab>
+</Tabs>
+
 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.

package/docs/en/cli/index.md

@@ -125,7 +125,7 @@ To see how to configure available locales, or other parameters, refer to the [co
 
 ### Authentication
 
-- **[Login](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/login.md)** - Authenticate with the Intlayer CMS and get access credentials
+- **[Login](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/login.md)** - Authenticate with the Intlayer CMS and get access credentials
 
 ### Core Commands
 

package/docs/en/cli/scan.md

@@ -150,10 +150,10 @@ await scan("https://example.com", {
 });
 ```
 
-For lower-level access, `scanWebsite` from `@intlayer/chokidar/scan` returns a structured `ScanResult` object:
+For lower-level access, `scanWebsite` from `@intlayer/engine/scan` returns a structured `ScanResult` object:
 
 ```ts
-import { scanWebsite } from "@intlayer/chokidar/scan";
+import { scanWebsite } from "@intlayer/engine/scan";
 
 const result = await scanWebsite("https://example.com", { deep: false });
 console.log(result.score, result.totalPageSize, result.events);

package/docs/en/configuration.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-06-23
+updatedAt: 2026-07-11
 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.0.0
+    date: 2026-07-11
+    changes: "Add `analytics` configuration"
   - version: 9.0.0
     date: 2026-06-24
     changes: "Add `enableProxy` option to the routing configuration"
@@ -365,6 +368,30 @@ const config: IntlayerConfig = {
     liveSync: true,
   },
 
+  /**
+   * Analytics configuration.
+   */
+  analytics: {
+    /**
+     * Whether analytics collection is enabled (page views, content exposures, A/B events).
+     * Requires `editor.clientId` to be set for attribution.
+     * Default: false
+     */
+    enabled: true,
+
+    /**
+     * Milliseconds between automatic batched flushes to the backend.
+     * Default: 20000
+     */
+    flushInterval: 20000,
+
+    /**
+     * Fraction of sessions to record, from 0 (none) to 1 (all).
+     * Default: 1
+     */
+    sampleRate: 1,
+  },
+
   /**
    * AI-powered translation and generation settings.
    */
@@ -680,6 +707,20 @@ Defines settings related to the integrated editor, including server port and act
 | `liveSyncPort`               | The port of the live sync server.                                                                                                                               | `number`                          | `4000`                              | `4000`                                                                                          |                                                                                                                                                                                                                      |
 | `liveSyncURL`                | The URL of the live sync server.                                                                                                                                | `string`                          | `'http://localhost:{liveSyncPort}'` | `'https://example.com'`                                                                         | Points to localhost by default; can be changed for a remote live sync server.                                                                                                                                        |
 
+### Analytics Configuration
+
+Defines settings related to Intlayer analytics: collecting which content is actually shown to users (page views, content exposures) and powering content A/B testing.
+
+Analytics is strictly opt-in: nothing is collected unless `analytics.enabled` is explicitly set to `true` **and** a project key (`editor.clientId`) is configured for attribution. When disabled (the default), the whole analytics integration is dead-code-eliminated from your application bundle.
+
+| Field           | Description                                                               | Type      | Default | Example | Note                                                                                                                  |
+| --------------- | ------------------------------------------------------------------------- | --------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
+| `enabled`       | Enables analytics collection (page views, content exposures, A/B events). | `boolean` | `false` | `true`  | Requires `editor.clientId` to be set for attribution; otherwise analytics stays disabled even if `enabled` is `true`. |
+| `flushInterval` | Milliseconds between automatic batched flushes to the backend.            | `number`  | `20000` | `10000` |                                                                                                                       |
+| `sampleRate`    | Fraction of sessions to record, from `0` (none) to `1` (all).             | `number`  | `1`     | `0.5`   | Sampling is deterministic per session, so a recorded session reports all of its events (no partial funnels).          |
+
+---
+
 ### Routing Configuration
 
 Settings that control routing behavior, including URL structure, locale storage, and middleware handling.

package/docs/en/how_works_intlayer.md

@@ -220,9 +220,9 @@ The `@intlayer/mcp` package provides an MCP (Model Context Protocol) server that
 
 The `@intlayer/dictionaries-entry`, `@intlayer/unmerged-dictionaries-entry` and `@intlayer/dynamic-dictionaries-entry` packages return the entry path of the Intlayer dictionaries. Since searching the filesystem from the browser is impossible, using bundlers like Webpack or Rollup to retrieve the entry path of the dictionaries is not possible. These packages are designed to be aliased, allowing for bundling optimization across various bundlers such as Vite, Webpack, and Turbopack.
 
-### @intlayer/chokidar
+### @intlayer/engine
 
-The `@intlayer/chokidar` package is used to monitor content files and regenerate the modified dictionary at each modification.
+The `@intlayer/engine` package is used to monitor content files and regenerate the modified dictionary at each modification.
 
 ### @intlayer/editor