@intlayer/docs 9.0.0-canary.15 → 9.0.0-canary.16

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/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/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/intlayer_CMS.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-08-23
-updatedAt: 2026-06-29
+updatedAt: 2026-07-08
 title: Intlayer CMS | Externalize your content into the Intlayer CMS
 description: Externalize your content into the Intlayer CMS to delegate the management of your content to your team.
 keywords:
@@ -18,6 +18,9 @@ slugs:
   - cms
 youtubeVideo: https://www.youtube.com/watch?v=UDDTnirwi_4
 history:
+  - version: 9.0.0
+    date: 2026-07-08
+    changes: "Move Live Sync section to its own page (live-sync.md), keep a short intro + link here"
   - version: 9.0.0
     date: 2026-06-30
     changes: "Add Self-Hosting section: Docker Compose bootstrap, service inventory, SDK configuration, optional features, and upgrade notes"
@@ -401,146 +404,9 @@ await pushDictionaries([{ key: "home", content: { title: "Home" } }]);
 
 ## Live sync
 
-Live Sync lets your app reflect CMS content changes at runtime. No rebuild or redeploy required. When enabled, updates are streamed to a Live Sync server that refreshes the dictionaries your application reads.
-
-Enable Live Sync by updating your Intlayer configuration:
-
-```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
-import type { IntlayerConfig } from "intlayer";
-
-const config: IntlayerConfig = {
-  // ... other configuration settings
-  editor: {
-    /**
-     * Enables hot reloading of locale configurations when changes are detected.
-     * For example, when a dictionary is added or updated, the application updates
-     * the content displayed on the page.
-     *
-     * Because hot reloading requires a continuous connection to the server, it is
-     * only available for clients of the `enterprise` plan.
-     *
-     * Default: false
-     */
-    liveSync: true,
-  },
-  dictionary: {
-    /**
-     * Controls how dictionaries are imported:
-     *
-     * - "fetch": Dictionaries are fetched dynamically using the Live Sync API.
-     *   Replaces useIntlayer with useDictionaryDynamic.
-     *
-     * Note: Live mode uses the Live Sync API to fetch dictionaries. If the API call
-     * fails, dictionaries are imported dynamically.
-     * Note: Only dictionaries with remote content and "live" flags use live mode.
-     * Others use dynamic mode for performance.
-     */
-    importMode: "fetch",
-  },
-};
-
-export default config;
-```
-
-Start the Live Sync server to wrap your application:
-
-Example using standalone server:
-
-```json5 fileName="package.json"
-{
-  "scripts": {
-    // ... other scripts
-    "live:start": "npx intlayer live",
-  },
-}
-```
-
-You can also use your application server in parallel using the `--process` argument.
-
-Example using Next.js:
-
-```json5 fileName="package.json"
-{
-  "scripts": {
-    // ... other scripts
-    "build": "next build",
-    "dev": "next dev",
-    "start": "npx intlayer live --with 'next start'",
-  },
-}
-```
-
-Example using Vite:
-
-```json5 fileName="package.json"
-{
-  "scripts": {
-    // ... other scripts
-    "build": "vite build",
-    "dev": "vite dev",
-    "start": "npx intlayer live --with 'vite start'",
-  },
-}
-```
-
-The Live Sync server wraps your application and automatically applies updated content as it arrives.
-
-To receive change notifications from the CMS, the Live Sync server maintains an SSE connection to the backend. When content changes in the CMS, the backend forwards the update to the Live Sync server, which writes the new dictionaries. Your application will reflect the update on the next navigation or browser reload, no rebuild required.
-
-Flow chart (CMS/Backend -> Live Sync Server -> Application Server -> Frontend):
-
-![Live Sync Flow CMS/Backend/Live Sync Server/Application Server/Frontend Schema](https://github.com/aymericzip/intlayer/blob/main/docs/assets/live_sync_flow_scema.svg)
-
-How it works:
-
-![Live Sync Logic Schema](https://github.com/aymericzip/intlayer/blob/main/docs/assets/live_sync_logic_schema.svg)
-
-### Development workflow (local)
-
-- In development, all remote dictionaries are fetched when the application starts, so you can test updates quickly.
-- To test Live Sync locally with Next.js, wrap your dev server:
-
-```json5 fileName="package.json"
-{
-  "scripts": {
-    // ... other scripts
-    "dev": "npx intlayer live --with 'next dev'",
-    // "dev": "npx intlayer live --with 'vite dev'", // For Vite
-  },
-}
-```
-
-Enable optimization so Intlayer applies the Live import transformations during development:
-
-```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
-import type { IntlayerConfig } from "intlayer";
-
-const config: IntlayerConfig = {
-  editor: {
-    applicationURL: "http://localhost:5173",
-    liveSyncURL: "http://localhost:4000",
-    liveSync: true,
-  },
-  dictionary: {
-    importMode: "fetch",
-  },
-  build: {
-    optimize: true, // default: process.env.NODE_ENV === 'production'
-  },
-};
-
-export default config;
-```
-
-This setup wraps your dev server with the Live Sync server, fetches remote dictionaries at startup, and streams updates from the CMS via SSE. Refresh the page to see changes.
-
-Notes and constraints:
+Live Sync lets your app reflect CMS content changes at runtime — no rebuild or redeploy required. When enabled, updates are streamed to a Live Sync server that refreshes the dictionaries your application reads.
 
-- Add the live sync origin to your site security policy (CSP). Ensure the live sync URL is allowed in `connect-src` (and `frame-ancestors` if relevant).
-- Live Sync does not work with static output. For Next.js, the page must be dynamic to receive updates at runtime (e.g., use `generateStaticParams`, `generateMetadata`, `getServerSideProps`, or `getStaticProps` appropriately to avoid full static-only constraints).
-- In the CMS, each dictionary has a `live` flag. Only dictionaries with `live=true` are fetched via the live sync API; others are imported dynamically and remain unchanged at runtime.
-- The `live` flag is evaluated for each dictionary at build time. If remote content wasn't flagged `live=true` during build, you must rebuild to enable Live Sync for that dictionary.
-- The live sync server must be able to write to `.intlayer`. In containers, ensure write access to `/.intlayer`.
+For the full setup guide (configuration, starting the Live Sync server, the local development workflow, and constraints), see the [Live Sync documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/live-sync.md).
 
 ## Self-Hosting
 

package/docs/en/live-sync.md

@@ -0,0 +1,184 @@
+---
+createdAt: 2026-07-08
+updatedAt: 2026-07-08
+title: Live Sync | Reflect CMS content changes at runtime
+description: Let your app reflect Intlayer CMS content changes at runtime, with no rebuild or redeploy required.
+keywords:
+  - Live Sync
+  - CMS
+  - Visual Editor
+  - Internationalization
+  - Documentation
+  - Intlayer
+  - Next.js
+  - Vite
+history:
+  - version: 9.0.0
+    date: 2026-07-08
+    changes: "Extracted from the Intlayer CMS documentation into its own page"
+  - version: 6.0.1
+    date: 2025-09-22
+    changes: "Add live sync documentation"
+  - version: 6.0.0
+    date: 2025-09-04
+    changes: "Replace `hotReload` field by `liveSync`"
+author: aymericzip
+---
+
+# Intlayer Live Sync
+
+Live Sync lets your app reflect [Intlayer CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md) content changes at runtime. No rebuild or redeploy required. When enabled, updates are streamed to a Live Sync server that refreshes the dictionaries your application reads.
+
+## Table of Contents
+
+<TOC/>
+
+---
+
+## Enabling Live Sync
+
+Enable Live Sync by updating your Intlayer configuration:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  // ... other configuration settings
+  editor: {
+    /**
+     * Enables hot reloading of locale configurations when changes are detected.
+     * For example, when a dictionary is added or updated, the application updates
+     * the content displayed on the page.
+     *
+     * Because hot reloading requires a continuous connection to the server, it is
+     * only available for clients of the `enterprise` plan.
+     *
+     * Default: false
+     */
+    liveSync: true,
+  },
+  dictionary: {
+    /**
+     * Controls how dictionaries are imported:
+     *
+     * - "fetch": Dictionaries are fetched dynamically using the Live Sync API.
+     *   Replaces useIntlayer with useDictionaryDynamic.
+     *
+     * Note: Live mode uses the Live Sync API to fetch dictionaries. If the API call
+     * fails, dictionaries are imported dynamically.
+     * Note: Only dictionaries with remote content and "live" flags use live mode.
+     * Others use dynamic mode for performance.
+     */
+    importMode: "fetch",
+  },
+};
+
+export default config;
+```
+
+Start the Live Sync server to wrap your application:
+
+Example using standalone server:
+
+```json5 fileName="package.json"
+{
+  "scripts": {
+    // ... other scripts
+    "live:start": "npx intlayer live",
+  },
+}
+```
+
+You can also use your application server in parallel using the `--process` argument.
+
+Example using Next.js:
+
+```json5 fileName="package.json"
+{
+  "scripts": {
+    // ... other scripts
+    "build": "next build",
+    "dev": "next dev",
+    "start": "npx intlayer live --with 'next start'",
+  },
+}
+```
+
+Example using Vite:
+
+```json5 fileName="package.json"
+{
+  "scripts": {
+    // ... other scripts
+    "build": "vite build",
+    "dev": "vite dev",
+    "start": "npx intlayer live --with 'vite start'",
+  },
+}
+```
+
+The Live Sync server wraps your application and automatically applies updated content as it arrives.
+
+To receive change notifications from the CMS, the Live Sync server maintains an SSE connection to the backend. When content changes in the CMS, the backend forwards the update to the Live Sync server, which writes the new dictionaries. Your application will reflect the update on the next navigation or browser reload, no rebuild required.
+
+Flow chart (CMS/Backend -> Live Sync Server -> Application Server -> Frontend):
+
+![Live Sync Flow CMS/Backend/Live Sync Server/Application Server/Frontend Schema](https://github.com/aymericzip/intlayer/blob/main/docs/assets/live_sync_flow_scema.svg)
+
+How it works:
+
+![Live Sync Logic Schema](https://github.com/aymericzip/intlayer/blob/main/docs/assets/live_sync_logic_schema.svg)
+
+## Development workflow (local)
+
+- In development, all remote dictionaries are fetched when the application starts, so you can test updates quickly.
+- To test Live Sync locally with Next.js, wrap your dev server:
+
+```json5 fileName="package.json"
+{
+  "scripts": {
+    // ... other scripts
+    "dev": "npx intlayer live --with 'next dev'",
+    // "dev": "npx intlayer live --with 'vite dev'", // For Vite
+  },
+}
+```
+
+Enable optimization so Intlayer applies the Live import transformations during development:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  editor: {
+    applicationURL: "http://localhost:5173",
+    liveSyncURL: "http://localhost:4000",
+    liveSync: true,
+  },
+  dictionary: {
+    importMode: "fetch",
+  },
+  build: {
+    optimize: true, // default: process.env.NODE_ENV === 'production'
+  },
+};
+
+export default config;
+```
+
+This setup wraps your dev server with the Live Sync server, fetches remote dictionaries at startup, and streams updates from the CMS via SSE. Refresh the page to see changes.
+
+## Notes and constraints
+
+- Add the live sync origin to your site security policy (CSP). Ensure the live sync URL is allowed in `connect-src` (and `frame-ancestors` if relevant).
+- Live Sync does not work with static output. For Next.js, the page must be dynamic to receive updates at runtime (e.g., use `generateStaticParams`, `generateMetadata`, `getServerSideProps`, or `getStaticProps` appropriately to avoid full static-only constraints).
+- In the CMS, each dictionary has a `live` flag. Only dictionaries with `live=true` are fetched via the live sync API; others are imported dynamically and remain unchanged at runtime.
+- The `live` flag is evaluated for each dictionary at build time. If remote content wasn't flagged `live=true` during build, you must rebuild to enable Live Sync for that dictionary.
+- The live sync server must be able to write to `.intlayer`. In containers, ensure write access to `/.intlayer`.
+
+## Useful links
+
+- [Intlayer CMS](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)