@intlayer/docs 9.3.3 → 9.4.0

package/docs/en/packages/vite-intlayer/intlayerMinify.md

@@ -56,7 +56,7 @@ export default defineConfig({
 2. `build.optimize` is `true` (or `undefined`, which defaults to `true` for builds).
 3. `build.minify` is `true` in your Intlayer config.
 
-It is automatically **disabled** when `editor.enabled` is `true` because the editor needs the full, human-readable dictionary content.
+When `editor.enabled` is `true`, the plugin still runs but **skips field renaming**: renaming rewrites the content keys the interpreter walks, so the `keyPath` the visual editor receives would no longer match the unmerged dictionaries it edits. Whitespace compaction and the top-level metadata strip stay active.
 
 ## What gets minified
 

package/docs/en/packages/vite-intlayer/intlayerPrune.md

@@ -120,4 +120,4 @@ When pruning succeeds, `intlayerPrune` also writes `pruneContext.dictionaryKeyTo
 2. `build.optimize` is `true` (or `undefined`, which defaults to `true` for builds).
 3. `build.purge` is `true` in your Intlayer config.
 
-It is automatically **disabled** when `editor.enabled` is `true` because the editor needs the full dictionary content.
+It stays active when `editor.enabled` is `true`: the visual editor resolves every edit through `dictionaryKey` + `keyPath` against the unmerged dictionaries, which this plugin never touches, and a purged field is one no component reads — so it is never rendered and never selectable in the page.

package/docs/en/readme.md

@@ -235,6 +235,7 @@ Explore our comprehensive documentation to get started with Intlayer and learn h
       <li><a href="https://intlayer.org/doc/environment/fastify" rel=''>Fastify</a></li>
       <li><a href="https://intlayer.org/doc/environment/adonisjs" rel=''>AdonisJS</a></li>
       <li><a href="https://intlayer.org/doc/environment/hono" rel=''>Hono</a></li>
+      <li><a href="https://intlayer.org/doc/environment/elysia" rel=''>Elysia</a></li>
     </ul>
   </li>
 </ul>

package/docs/en/self_hosting.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-06-30
-updatedAt: 2026-07-02
+updatedAt: 2026-08-23
 title: Self-Hosting Intlayer
 description: Run a complete Intlayer instance on your own infrastructure with a single container. No Intlayer Cloud account required.
 keywords:
@@ -20,6 +20,14 @@ author: aymericzip
 
 Intlayer can run on your own infrastructure. No Intlayer Cloud account required. A single all-in-one Docker image bundles the dashboard, the API, and the local datastores (Redis and MinIO) it needs, supervised by [s6-overlay](https://github.com/just-containers/s6-overlay).
 
+One command installs everything:
+
+```sh
+curl -fsSL https://intlayer.org/install.sh | sh
+```
+
+The installer checks for Docker (offering to install it), writes an `intlayer.env` file with your secrets already generated, and pulls the image. It then asks you to fill in your credentials and prints the `docker run` command — see [Quick start](#quick-start).
+
 The only external dependency is **MongoDB**: the backend connects to a MongoDB **Atlas** cluster, which you provide. Everything else runs inside the container.
 
 ## Table of Contents
@@ -51,38 +59,84 @@ Chromium (used for Puppeteer screenshot generation) is bundled inside the image.
 
 ## Prerequisites
 
-- **Docker** ≥ 24.
+- **Docker** ≥ 24. The installer offers to install it for you if it is missing (via [get.docker.com](https://get.docker.com) on Linux, Homebrew on macOS).
 - Ports `3000`, `3100`, `9000`, and `9001` available on the host.
 - A Linux or macOS host (or WSL2 on Windows).
 - A **MongoDB Atlas** cluster (a free tier works). Create one at [mongodb.com/atlas](https://www.mongodb.com/atlas).
-- A **Resend** API key for transactional email. Get one at [resend.com](https://resend.com).
+- A **Resend** API key for transactional email. Get one at [resend.com](https://resend.com). A [global SMTP mailer](#global-mailer) works instead.
+
+Everything else — Bun, Redis, MinIO, Chromium — ships inside the image.
 
 ---
 
 ## Quick start
 
-Pull and run the published image, supplying your MongoDB Atlas credentials and secrets:
+### 1. Run the installer
+
+```sh
+curl -fsSL https://intlayer.org/install.sh | sh
+```
+
+It verifies Docker is installed and running, writes `./intlayer.env` with `BETTER_AUTH_SECRET` and `S3_SECRET_ACCESS_KEY` already generated, and pulls the image. It does not start the container — the backend cannot boot without your database credentials.
+
+Re-running the installer is safe: an existing `intlayer.env` is never overwritten, so it doubles as the upgrade path.
+
+### 2. Fill in your credentials
+
+Open `intlayer.env` and complete the values marked `TODO`:
+
+```sh fileName="intlayer.env"
+DB_ID=<atlas-user>
+DB_MDP=<atlas-password>
+DB_CLUSTER=<cluster>.xxxxx.mongodb.net
+RESEND_API_KEY=<your-resend-key>
+```
+
+The file also carries commented-out blocks for the optional features — [SMTP mailer](#global-mailer), `OPENAI_API_KEY`, and the OAuth providers. Uncomment what you need.
+
+> The file is read by `docker run --env-file`, which does not strip quotes and treats everything after `=` as the value. Write bare values, and keep comments on their own lines.
+
+### 3. Start the container
+
+This is the command the installer prints when it finishes:
 
 ```sh
 docker run -d --name intlayer \
+  --restart unless-stopped \
   -p 3000:3000 \
   -p 3100:3100 \
   -p 9000:9000 \
   -p 9001:9001 \
   -v intlayer-data:/data \
-  -e DB_ID="<atlas-user>" \
-  -e DB_MDP="<atlas-password>" \
-  -e DB_CLUSTER="<cluster>.xxxxx.mongodb.net" \
-  -e BETTER_AUTH_SECRET="$(openssl rand -hex 32)" \
-  -e S3_SECRET_ACCESS_KEY="$(openssl rand -hex 16)" \
-  -e RESEND_API_KEY="<your-resend-key>" \
-  aymericzip/intlayer-selfhost
+  --env-file ./intlayer.env \
+  ghcr.io/aymericzip/intlayer-selfhost:latest
 ```
 
-Then open **http://localhost:3000**.
+Then open **http://localhost:3000**. First boot initialises the datastores, so give it a minute.
 
 > The dashboard is served on `localhost`. See [Limitations](#limitations) — custom domains are not supported by the published image.
 
+### Installer settings
+
+The installer reads a few environment variables. Because it is piped into `sh`, pass them to the shell rather than to `curl`:
+
+```sh
+curl -fsSL https://intlayer.org/install.sh | INTLAYER_ENV_FILE=./config/intlayer.env sh
+```
+
+| Variable                  | Default                                       | Description                     |
+| ------------------------- | --------------------------------------------- | ------------------------------- |
+| `INTLAYER_IMAGE`          | `ghcr.io/aymericzip/intlayer-selfhost:latest` | Image to pull                   |
+| `INTLAYER_ENV_FILE`       | `./intlayer.env`                              | Where to write the env file     |
+| `INTLAYER_CONTAINER_NAME` | `intlayer`                                    | Container name                  |
+| `INTLAYER_DATA_VOLUME`    | `intlayer-data`                               | Named volume mounted at `/data` |
+| `INTLAYER_APP_PORT`       | `3000`                                        | Host port for the dashboard     |
+| `INTLAYER_API_PORT`       | `3100`                                        | Host port for the API           |
+| `INTLAYER_S3_PORT`        | `9000`                                        | Host port for the MinIO S3 API  |
+| `INTLAYER_CONSOLE_PORT`   | `9001`                                        | Host port for the MinIO console |
+
+> The four port variables only change the **host** side of the mapping printed in the `docker run` command. The published image has `http://localhost:3000`, `http://localhost:3100` and `http://localhost:9000` compiled into the dashboard bundle at build time, so remapping them leaves the browser pointing at the old ports. Keep the defaults unless you are building your own image — see [Limitations](#limitations).
+
 ---
 
 ## First-run setup
@@ -123,6 +177,7 @@ Once an admin exists, `/init` redirects to the standard sign-in page.
 | `BETTER_AUTH_SECRET`   | _(generated)_                | 32-byte secret for session signing                                                                                                           |
 | `S3_SECRET_ACCESS_KEY` | _(generated)_                | Secret for the bundled MinIO                                                                                                                 |
 | `RESEND_API_KEY`       | _(your key)_                 | Transactional email via Resend. Required for first-run setup unless you configure a global SMTP mailer (see [Global mailer](#global-mailer)) |
+| `SELF_HOSTED`          | `true`                       | Disables the cloud-only API endpoints: Stripe billing, subscriptions, affiliate and promo-code programs, and the reviewer marketplace        |
 
 ### Baked-in defaults (override only if needed)
 
@@ -234,12 +289,12 @@ const { data: dictionaries } = await dictionaryEndpoint(cms).getDictionaries();
 
 ## Upgrading
 
-Pull the latest image and recreate the container. Your data is preserved in the named volume (MinIO/Redis) and in your Atlas cluster (MongoDB):
+Re-run the installer to pull the latest image, then recreate the container. Your `intlayer.env` is left untouched, and your data is preserved in the named volume (MinIO/Redis) and in your Atlas cluster (MongoDB):
 
 ```sh
-docker pull aymericzip/intlayer-selfhost
-docker stop intlayer && docker rm intlayer
-# re-run the `docker run …` command from Quick start
+curl -fsSL https://intlayer.org/install.sh | sh
+docker rm -f intlayer
+# re-run the `docker run …` command from step 3 of Quick start
 ```
 
 ---
@@ -271,7 +326,7 @@ docker run --rm \
 ## Limitations
 
 - **MongoDB must be external (Atlas).** The backend connects only over `mongodb+srv://` (built from `DB_ID` / `DB_MDP` / `DB_CLUSTER`), so a plain `mongodb://host:27017` — including the container's own bundled `mongod` — cannot be used. Provide a MongoDB Atlas cluster.
-- **No custom domain.** All browser-facing `VITE_*` URLs are inlined into the app at build time, and the published image ships with `localhost` values. The dashboard must be accessed at `http://localhost:3000`; serving it on a public domain would require rebuilding the image with the target URLs baked in and is not supported out of the box.
+- **No custom domain, and no port remapping.** All browser-facing `VITE_*` URLs are inlined into the app at build time, and the published image ships with `localhost` values. The dashboard must be accessed at `http://localhost:3000`, the API at `:3100` and MinIO at `:9000`; serving it on a public domain — or on different ports — would require rebuilding the image with the target URLs baked in (`--build-arg VITE_BACKEND_URL=…`) and is not supported out of the box.
 - **Email requires a working mailer.** First-run setup enforces email verification, so either `RESEND_API_KEY` or a [global SMTP mailer](#global-mailer) (`MAIL_PROVIDER=smtp` + `MAIL_SMTP_*`) must be configured. After the first admin signs in, each organization can also configure its own SMTP or Resend mailer from the dashboard.
 
 ---
@@ -280,13 +335,14 @@ docker run --rm \
 
 ### Dashboard loads but the API resets the connection (`ERR_CONNECTION_RESET` on `:3100`)
 
-The backend crashed on startup and is not listening. The most common cause is a missing or invalid MongoDB connection: check that `DB_ID`, `DB_MDP`, and `DB_CLUSTER` are set and correct.
+The backend crashed on startup and is not listening. The most common cause is a missing or invalid MongoDB connection — usually the `TODO` values in `intlayer.env` were never filled in:
 
 ```sh
+grep -E '^DB_(ID|MDP|CLUSTER)=' intlayer.env
 docker logs intlayer
 ```
 
-Look for `MongoDB connection error` near the top of the log.
+Look for `MongoDB connection error` near the top of the log. After correcting `intlayer.env`, recreate the container (`docker rm -f intlayer`, then the `docker run …` command again) — `--env-file` is read at creation time, so editing the file does not affect a running container.
 
 ### First account can't be verified
 
@@ -307,4 +363,5 @@ docker restart intlayer
 - [Intlayer CMS documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)
 - [Configuration reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md)
 - [CMS SDK — `@intlayer/api`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md#programmatic-access-with-the-intlayerapi-sdk)
-- [Docker Image (aymercizip/intlayer-selfhost)](https://hub.docker.com/repository/docker/aymercizip/intlayer-selfhost/general)
+- [Container image on GHCR](https://github.com/aymericzip/intlayer/pkgs/container/intlayer-selfhost) — `ghcr.io/aymericzip/intlayer-selfhost`
+- [Container image on Docker Hub](https://hub.docker.com/r/aymericzip/intlayer-selfhost) — mirror of the same build

package/docs/en-GB/analytics.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-07-08
-updatedAt: 2026-07-08
+updatedAt: 2026-08-22
 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:
@@ -18,6 +18,9 @@ slugs:
   - concept
   - analytics
 history:
+  - version: 9.3.3
+    date: 2026-08-22
+    changes: "Enable analytics by default — active as soon as `@intlayer/analytics` is installed"
   - version: 9.0.0
     date: 2026-07-08
     changes: "Init doc — @intlayer/analytics package, provider/node-level tracking, A/B testing, dashboard"
@@ -57,7 +60,7 @@ Intlayer already lets you declare content [Variants](https://github.com/aymericz
 
 ## Installation
 
-`@intlayer/analytics` is a **peer, optional** dependency — never installed automatically by a framework package. Add it alongside `intlayer`:
+`@intlayer/analytics` is an **optional dependency** of every framework package (`react-intlayer`, `next-intlayer`, `vue-intlayer`, …), so most projects already have it. Install it explicitly if your setup skips optional dependencies (`npm install --no-optional`, …):
 
 ```bash packageManager="npm"
 npm install @intlayer/analytics
@@ -75,11 +78,11 @@ pnpm add @intlayer/analytics
 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.
+Installing the package is all it takes to turn analytics on: `analytics.enabled` defaults to `true`, and `@intlayer/config` resolves it to `false` whenever the package cannot be found in your project. 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:
+Analytics needs no configuration to start: it is **enabled by default** and **reuses the existing `editor` configuration block** for its endpoint and project key.
 
 ```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import type { IntlayerConfig } from "intlayer";
@@ -100,6 +103,26 @@ export default config;
 
 If you self-host Intlayer, analytics automatically points at your own instance since it shares `editor.backendURL`.
 
+### Opting out
+
+The optional `analytics` block tunes — or turns off — the collection:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  analytics: {
+    enabled: false, // Default: true — opts the whole integration out of the bundle
+    flushInterval: 20_000, // Milliseconds between two batched flushes
+    sampleRate: 1, // Fraction of sessions to record, from 0 (none) to 1 (all)
+  },
+};
+
+export default config;
+```
+
+Uninstalling `@intlayer/analytics` has the same effect as `enabled: false`. See the [Configuration reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md) for the full field list.
+
 ## Framework support
 
 Analytics is wired into the shared `IntlayerProvider` from `react-intlayer`, so it is available today anywhere that provider is used:
@@ -177,7 +200,7 @@ const variant = client?.getVariant("homepage-hero", [
 `@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;
+- a compile-time env var (`INTLAYER_ANALYTICS_ENABLED`), automatically set to `'false'` by `@intlayer/config` whenever the package is not installed, `analytics.enabled` is `false`, or `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

package/docs/en-GB/benchmark/tanstack.md

@@ -194,6 +194,8 @@ The idea behind `Wuchale` is interesting but not yet a viable solution. I hit re
 
 `Tolgee` addresses many of the issues mentioned earlier. I found it harder to get started with than other tools with similar approaches. It does not provide type safety, which also makes catching missing keys at compile time much harder. I had to wrap Tolgee’s APIs with my own to add missing-key detection.
 
+The package is fairly heavy (~11.1kb, which is more than 2× `react-intlayer`).
+
 On TanStack Start I also had reactivity problems: on locale change I had to force the provider to rerender and subscribe to locale-change events so loading in another language behaved correctly.
 
 **(use-intl)** (`use-intl@4.9.1`):
@@ -208,6 +210,8 @@ On TanStack Start you avoid Next.js-specific traps (`setRequestLocale`, static r
 
 Still, it shares the same major downsides as stacks built on `t('a.b.c')`: optimisations are possible but very time-consuming, and large projects risk bad practices (namespaces + dynamic loading + types).
 
+The package is especially heavy (~17.3kb, which is about 3.5× `react-intlayer`).
+
 Message formats also diverge: `use-intl` uses ICU MessageFormat, while `i18next` uses its own format-which complicates tooling or migrations if you mix them.
 
 **(Lingui)** (`@lingui/core@5.3.0`):
@@ -218,6 +222,8 @@ Message formats also diverge: `use-intl` uses ICU MessageFormat, while `i18next`
 
 `react-intl` is a performant implementation from the Format.js team. The DX stays verbose: `const intl = useIntl()` + `intl.formatMessage({ id: "xx.xx" })` adds complexity, extra JavaScript work, and ties the global i18n instance to many nodes in the React tree.
 
+The package is also heavy (~14.4kb, which is about 3× `react-intlayer`).
+
 ### 4 - Recommendations
 
 This TanStack Start benchmark has no direct equivalent to `next-translate` (Next.js plugin + `getStaticProps`). For teams that really want a `t()` API with a mature ecosystem, `react-i18next` and `use-intl` remain “reasonable” choices, but expect to invest a lot of time optimising to avoid leakage.

package/docs/en-GB/bundle_optimization.md

@@ -476,7 +476,7 @@ const config: IntlayerConfig = {
 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).
+> Minification is skipped when `optimize` is `false`. When `editor.enabled` is `true` it still runs, but without the field-renaming step — the visual editor resolves edits by `keyPath`, so the original field names have to survive.
 
 > 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.
 
@@ -508,7 +508,7 @@ export default config;
 { "title": "…", "subtitle": "…" }
 ```
 
-> 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 skipped when `optimize` is `false`. It stays active when `editor.enabled` is `true` — a purged field is read by no component, so the editor never renders it. 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/cli/ci.md

@@ -128,6 +128,8 @@ bun x intlayer ci fill --verbose --mode complete
 
 ### Use in CI/CD pipelines
 
+Running `intlayer init` scaffolds two ready-to-use GitHub Actions workflows for you (see [Scaffolded GitHub Actions](#scaffolded-github-actions) below). The example here shows the equivalent setup using the `ci` command for a monorepo, where credentials are injected per project from `INTLAYER_PROJECT_CREDENTIALS`.
+
 In your CI/CD configuration (e.g., GitHub Actions, GitLab CI), set the `INTLAYER_PROJECT_CREDENTIALS` as a secret:
 
 ```yaml

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

@@ -89,9 +89,15 @@ For most use cases,
 
 **Review mode options:**
 
+- **`--mode [mode]`**: How the review runs. Defaults to `apply`.
+
 - **`--log`**: Log-only mode. Do not translate with AI; instead log the blocks that need attention (with line numbers and content) for the base and target locales, to help another agent generate the translations.
 
-  > Example: `npx intlayer doc review --log`
+> Example: `npx intlayer doc review --mode report`
+
+> Example: `npx intlayer doc review --log`
+
+Whatever the mode, the run ends with a synthesis listing the documents that are aligned with their base document and the ones that still have blocks to edit.
 
 **Entry output options:**
 

package/docs/en-GB/cli/fill.md

@@ -39,14 +39,6 @@ bun x intlayer fill
 
 This command analyses your content declaration files for potential issues such as missing translations, structural inconsistencies, or type mismatches. If it finds any problems, **intlayer fill** will propose or apply updates to keep your dictionaries consistent and complete.
 
-Key Points:
-
-- Splits large JSON files into chunks to stay within the AI model's context window limits.
-- Retries translation if the output format is incorrect.
-- Incorporates application and file-specific context for improved translation accuracy.
-- Preserves existing translations by not overwriting them.
-- Processes files, chunks, and locales in parallel using a queue system to increase speed.
-
 ## Key Points:
 
 - Splits large JSON files into chunks to stay within the AI model's context window limits.

package/docs/en-GB/cli/index.md

@@ -127,6 +127,8 @@ To learn how to configure the available languages or other parameters, take a lo
 
 - **[Login](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/login.md)** - Authenticate with the Intlayer CMS and get the access credentials
 
+> `intlayer login` issues an **access key** (`clientId` / `clientSecret`) that every credentialed command uses. The secret is a server-side credential and never reaches your client bundle — see [Keeping the access key safe](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/login.md#keeping-the-access-key-safe).
+
 ### Core Commands
 
 - **[Build Dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/build.md)** - Build your dictionaries from your content declaration files

package/docs/en-GB/cli/list_projects.md

@@ -52,8 +52,6 @@ This command searches for and lists all Intlayer projects by finding directories
 
   > Example: `npx intlayer projects list --base-dir /path/to/workspace`
 
-  > Example: `npx intlayer projects list --base-dir /path/to/workspace`
-
 - **`--git-root`**: Search from the git root directory rather than the base directory. This is useful for finding all Intlayer projects in a monorepo or git repository.
 
   > Example: `npx intlayer projects list --git-root`

package/docs/en-GB/cli/login.md

@@ -118,6 +118,34 @@ INTLAYER_CLIENT_SECRET=your_client_secret
 }
 ```
 
+## Keeping the access key safe
+
+`intlayer login` issues an **access key**: a `clientId` / `clientSecret` pair that every credentialed command (`push`, `pull`, `fill`, `configuration push`, `live`, …) uses to authenticate.
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+  },
+};
+
+export default config;
+```
+
+> **`clientSecret` is a server-side credential.** It grants full project-scoped API access — reading and writing your dictionaries, your project and your organisation. Keep it in `.env` (git-ignored) or your CI secret store, and never inline it in the configuration file.
+
+Intlayer enforces this rather than only documenting it:
+
+- `clientSecret` is **stripped from the configuration your bundler inlines**, so it cannot reach a browser bundle whatever framework integration you use. It is only ever read server-side, at runtime, from the environment.
+- `clientId` is different: it is the **public** project key, safe to ship, and used by [`@intlayer/analytics`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/analytics.md#how-events-are-authenticated) to obtain a short-lived, ingest-only token.
+
+Commenting `clientId` out is enough to disable every credentialed behaviour — remote dictionary fetching, CMS access, analytics — even when the environment variables are still defined.
+
+For CI pipelines, prefer the [`ci` command](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/ci.md), which injects the credentials for the duration of a single run instead of persisting them.
+
 ## Manual Configuration
 
 If the browser does not open automatically, you can manually visit the URL displayed in the terminal.

package/docs/en-GB/compiler.md

@@ -40,6 +40,12 @@ The **Intlayer Compiler** is a powerful tool designed to automate the process of
 
 ## Why Use the Intlayer Compiler?
 
+- **Automation**: Eliminates manual copy-pasting of content into dictionaries.
+
+- **Speed**: Optimised content extraction ensuring your build process remains fast.
+
+- **Developer Experience**: Keep content declarations right where they are used, improving maintainability.
+
 - **Automation**: Eliminates manual copy-pasting of content into dictionaries.
 - **Speed**: Optimised content extraction ensuring your build process remains fast.
 - **Developer Experience**: Keep content declarations right where they are used, improving maintainability.
@@ -54,6 +60,8 @@ Whilst the compiler offers an excellent "just works" experience, it also introdu
 - **Heuristic ambiguity**: The compiler must guess what is user-facing content vs. application logic (e.g., `className="active"`, status codes, product IDs). In complex codebases, this can lead to false positives or missed strings that require manual annotations and exceptions.
 - **Static-only extraction**: Compiler-based extraction relies on static analysis. Strings that only exist at runtime (API error codes, CMS fields, etc.) cannot be discovered or translated by the compiler alone, so you still need a complementary runtime i18n strategy.
 
+- **Static-only extraction**: Compiler-based extraction relies on static analysis. Strings that only exist at runtime (API error codes, CMS fields, etc.) cannot be discovered or translated by the compiler alone, so you still need a complementary runtime i18n strategy.
+
 For a deeper architectural comparison, see the blog post [Compiler vs. Declarative i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en-GB/compiler_vs_declarative_i18n.md).
 
 As an alternative, to automate your i18n process whilst keeping full control of your content, Intlayer also provides an auto-extraction command `intlayer extract` (see [CLI documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/extract.md)), or the `Intlayer: extract content to Dictionary` command from the Intlayer VS Code extension (see [VS Code extension documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/vs_code_extension.md)).
@@ -94,12 +102,18 @@ export default defineConfig({
 });
 ```
 
+> The standalone `intlayerCompiler()` plugin is still exported for advanced setups. Registering it alongside `intlayer()` is safe — the compiler deduplicates itself and runs only once.
+
 See complete tutorial: [Intlayer Compiler with Vite+React](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_vite+react_compiler.md)
 
 #### Framework Support
 
 The Vite plugin automatically detects and handles different file types:
 
+- **React / JSX / TSX**: Handled natively.
+
+- **Vue**: Requires `@intlayer/vue-compiler`.
+
 - **React / JSX / TSX**: Handled natively.
 - **Vue**: Requires `@intlayer/vue-compiler`.
 - **Svelte**: Requires `@intlayer/svelte-compiler`.

package/docs/en-GB/configuration.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-08-06
+updatedAt: 2026-08-22
 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.3.3
+    date: 2026-08-22
+    changes: "Enable analytics by default — active as soon as `@intlayer/analytics` is installed"
   - version: 9.1.3
     date: 2026-08-06
     changes: "Make `routing.enableProxy` tri-state: unset (auto), `true`, `false`"
@@ -380,8 +383,8 @@ const config: IntlayerConfig = {
   analytics: {
     /**
      * Whether analytics collection is enabled (page views, content exposures, A/B events).
-     * Requires `editor.clientId` to be set for attribution.
-     * Default: false
+     * Requires `@intlayer/analytics` to be installed, and `editor.clientId` to be set for attribution.
+     * Default: true
      */
     enabled: true,
 
@@ -739,13 +742,13 @@ Defines settings related to the integrated editor, including server port and act
 
 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.
+Analytics is opt-out: it is enabled by default, and starts collecting as soon as the `@intlayer/analytics` package is installed **and** a project key (`editor.clientId`) is configured for attribution. Set `analytics.enabled` to `false` — or leave the package uninstalled — and 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).          |
+| Field           | Description                                                               | Type      | Default | Example | Note                                                                                                                                                            |
+| --------------- | ------------------------------------------------------------------------- | --------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `enabled`       | Enables analytics collection (page views, content exposures, A/B events). | `boolean` | `true`  | `false` | Requires `@intlayer/analytics` to be installed and `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).                                                    |
 
 ---
 

package/docs/en-GB/custom_domains.md

@@ -138,6 +138,38 @@ getMultilingualUrls("/about", { currentDomain: "intlayer.org" });
 
 These absolute URLs are ready to use in `<link rel="alternate" hreflang="...">` tags for SEO.
 
+## Type Inference
+
+`routing.domains` is serialized into the generated module augmentation, so
+`getLocalizedUrl` and `getLocalizedPath` narrow their return type to the exact
+URL a domain-routed locale resolves to — the prefix suppression included.
+
+```ts
+// routing: { mode: 'prefix-no-default', domains: { en: 'intlayer.org', zh: 'intlayer.zh' } }
+
+getLocalizedUrl("/about", "zh");
+//     ^? "https://intlayer.zh/about" | "/about"
+
+getLocalizedPath("/about", "zh");
+//     ^? "/about"   (never an origin, and no /zh/ prefix)
+```
+
+The URL type is the **union** of the two values the function can return: the
+absolute URL on the locale's domain, and the relative one it returns when the
+page being rendered already lives on that domain. `getLocalizedPath` has no such
+ambiguity - it never emits an origin - so it stays a single literal.
+
+Locales that share a domain keep their normal prefix in the type as well:
+
+```ts
+getLocalizedUrl("/about", "fr");
+//     ^? "https://intlayer.org/fr/about" | "/fr/about"
+```
+
+> Regenerate the types (`npx intlayer build`, or any dev server run) after
+> changing `routing.domains` - the narrowing comes from the generated
+> `__RoutingRegistry`, not from the config file itself.
+
 ## Proxy Behaviour
 
 ### Next.js
@@ -170,6 +202,8 @@ GET intlayer.zh/about
 
 The `intlayerProxy` Vite plugin applies the same logic during development:
 
+> Since Intlayer v9, `intlayerProxy()` is bundled directly into the `intlayer()` plugin and enabled by default through the `routing.enableProxy` option (`true` by default). Registering it separately as shown below is now optional — it is kept for backward compatibility and for setups that need to control plugin order. Set `routing.enableProxy: false` to opt out. See the [v9 release notes](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/releases/v9.md).
+
 ```typescript fileName="vite.config.ts"
 import { defineConfig } from "vite";
 import { intlayer } from "vite-intlayer";

package/docs/en-GB/custom_url_rewrites.md

@@ -248,7 +248,7 @@ To ensure that the browser's address bar always reflects the "pretty" localised
 
 <Tabs group='framework'>
   <Tab label="Next.js" value="nextjs">
-  
+
     ```tsx
     'use client';
 
@@ -263,7 +263,7 @@ To ensure that the browser's address bar always reflects the "pretty" localised
   </Tab>
 
   <Tab label="React Router" value="reactrouter">
-  
+
     ```tsx
     'use client';
 
@@ -279,7 +279,7 @@ To ensure that the browser's address bar always reflects the "pretty" localised
   </Tab>
 
   <Tab label="Vue" value="vue">
-  
+
     ```vue
     <script setup>
     import { useRewriteURL } from "vue-intlayer";
@@ -291,7 +291,7 @@ To ensure that the browser's address bar always reflects the "pretty" localised
 
   </Tab>
   <Tab label="Solid" value="solid">
-  
+
     ```tsx
     import { useRewriteURL } from "solid-intlayer";
 
@@ -303,7 +303,7 @@ To ensure that the browser's address bar always reflects the "pretty" localised
 
   </Tab>
   <Tab label="Svelte" value="svelte">
-  
+
     ```svelte
     <script>
     import { useRewriteURL } from "svelte-intlayer";
@@ -340,6 +340,8 @@ export function middleware(request: NextRequest) {
 
 For SolidJS, Vue, and Svelte, the `intlayerProxy` Vite plugin manages the rewrites during development.
 
+> Since Intlayer v9, `intlayerProxy()` is bundled directly into the `intlayer()` plugin and enabled by default through the `routing.enableProxy` option (`true` by default). Registering it separately as shown below is now optional — it is kept for backward compatibility and for setups that need to control plugin order. Set `routing.enableProxy: false` to opt out. See the [v9 release notes](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/releases/v9.md).
+
 ```typescript fileName="vite.config.ts"
 import { defineConfig } from "vite";
 import { intlayer } from "vite-intlayer";