@intlayer/docs 9.1.3 → 9.3.0

package/docs/en-GB/intlayer_with_vite+vue.md

@@ -30,9 +30,7 @@ history:
 author: aymericzip
 ---
 
-# Getting Started Internationalising (i18n) with Intlayer and Vite and Vue
-
-See [Application Template](https://github.com/aymericzip/intlayer-vite-vue-template) on GitHub.
+# Translate your Vite and Vue website using Intlayer | Internationalisation (i18n)
 
 ## Table of Contents
 

package/docs/en-GB/live-sync.md

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

package/docs/en-GB/packages/intlayer/getLocalizedUrl.md

@@ -59,36 +59,44 @@ getLocalizedUrl(
 
 ## Parameters
 
-## Description
-
-The `getLocalizedUrl` function generates a localised URL by prefixing the given URL with the specified locale. It handles both absolute and relative URLs, ensuring that the correct locale prefix is applied based on the configuration.
-
----
-
-## Parameters
+### Required Parameters
 
 - `url: string`
   - **Description**: The original URL string to be prefixed with a locale.
   - **Type**: `string`
+  - **Required**: Yes
 
 - `currentLocale: Locales`
   - **Description**: The current locale for which the URL is being localised.
   - **Type**: `Locales`
-
-- `locales: Locales[]`
-  - **Description**: Optional array of supported locales. By default, the configured locales in the project are provided.
-  - **Type**: `Locales[]`
-  - **Default**: [`Project Configuration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/{{locale}}/configuration.md#middleware)
-
-- `defaultLocale: Locales`
-  - **Description**: The default locale for the application. By default, the configured default locale in the project is provided.
-  - **Type**: `Locales`
-  - **Default**: [`Project Configuration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/{{locale}}/configuration.md#middleware)
-
-- `prefixDefault: boolean`
-  - **Description**: Whether to prefix the URL for the default locale. By default, the configured value in the project is provided.
-  - **Type**: `boolean`
-  - **Default**: [`Project Configuration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/{{locale}}/configuration.md#middleware)
+  - **Required**: Yes
+
+### Optional Parameters
+
+- `options?: object`
+  - **Description**: Configuration object for URL localisation behaviour.
+  - **Type**: `object`
+  - **Required**: No (Optional)
+
+  - `options.locales?: Locales[]`
+    - **Description**: Array of supported locales. If not provided, uses the configured locales from your project configuration.
+    - **Type**: `Locales[]`
+    - **Default**: [`Project Configuration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md#middleware)
+
+  - `options.defaultLocale?: Locales`
+    - **Description**: The default locale for the application. If not provided, uses the configured default locale from your project configuration.
+    - **Type**: `Locales`
+    - **Default**: [`Project Configuration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md#middleware)
+
+  - `options.mode?: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'`
+    - **Description**: The URL routing mode for locale handling. If not provided, uses the configured mode from your project configuration.
+    - **Type**: `'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'`
+    - **Default**: [`Project Configuration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md#middleware)
+    - **Modes**:
+      - `prefix-no-default`: No prefix for default locale, prefix for all others
+      - `prefix-all`: Prefix for all locales including default
+      - `no-prefix`: No locale prefix in URL
+      - `search-params`: Use query parameters for locale (e.g., `?locale=fr`)
 
 ### Returns
 

package/docs/en-GB/packages/intlayer/getMultilingualUrls.md

@@ -50,26 +50,12 @@ getMultilingualUrls(
 
 ## Parameters
 
-## Parameters
+### Required Parameters
 
 - `url: string`
   - **Description**: The original URL string to be prefixed with locales.
   - **Type**: `string`
-
-- `locales: Locales[]`
-  - **Description**: Optional array of supported locales. Defaults to the configured locales in the project.
-  - **Type**: `Locales[]`
-  - **Default**: `localesDefault`
-
-- `defaultLocale: Locales`
-  - **Description**: The default locale for the application. Defaults to the configured default locale in the project.
-  - **Type**: `Locales`
-  - **Default**: `defaultLocaleDefault`
-
-- `prefixDefault: boolean`
-  - **Description**: Whether to prefix the default locale. Defaults to the configured value in the project.
-  - **Type**: `boolean`
-  - **Default**: `prefixDefaultDefault`
+  - **Required**: Yes
 
 ### Optional Parameters
 
@@ -107,6 +93,20 @@ getMultilingualUrls(
 
 ## Example Usage
 
+### Basic Usage (Uses Project Configuration)
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getMultilingualUrls, Locales } from "intlayer";
+
+// Uses your project's configuration for locales, defaultLocale, and mode
+getMultilingualUrls("/dashboard");
+// Output (assuming project config has en, fr with mode 'prefix-no-default'):
+// {
+//   en: "/dashboard",
+//   fr: "/fr/dashboard"
+// }
+```
+
 ### Relative URLs
 
 ```typescript codeFormat={["typescript", "esm", "commonjs"]}
@@ -141,38 +141,6 @@ getMultilingualUrls(
 
 ---
 
-## Edge Cases
-
-- **No Locale Segment:**
-
-```typescript
-getMultilingualUrls(
-  "/dashboard",
-  [Locales.ENGLISH, Locales.FRENCH],
-  Locales.ENGLISH,
-  false
-);
-// Output: {
-// en: "/dashboard",
-// fr: "/fr/dashboard"
-// }
-```
-
-```javascript codeFormat="commonjs"
-const { getMultilingualUrls, Locales } = require("intlayer");
-
-getMultilingualUrls(
-  "/dashboard",
-  [Locales.ENGLISH, Locales.FRENCH],
-  Locales.ENGLISH,
-  false
-);
-// Output: {
-//   en: "/dashboard",
-//   fr: "/fr/dashboard"
-// }
-```
-
 ### Absolute URLs
 
 ```typescript

package/docs/en-GB/packages/vite-intlayer/exports.md

@@ -48,3 +48,18 @@ import "vite-intlayer";
 | `intlayerProxy`      | Development middleware plugin to handle locale detection and routing. | -                                                                                                                         |
 | `intlayerMiddleware` | (**Deprecated**) Alias for `intlayerProxy`.                           | -                                                                                                                         |
 | `intlayerPrune`      | Plugin to tree-shake and prune unused dictionaries during the build.  | [intlayerPrune](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/vite-intlayer/intlayerPrune.md) |
+
+### Utilities
+
+| Export                       | Description                                                                                   | Related Doc                                                                                                               |
+| ---------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `createIntlayerProxyHandler` | Returns a framework-agnostic Node.js `(req, res, next)` middleware with locale-routing logic. | [intlayerProxy](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/vite-intlayer/intlayerProxy.md) |
+
+### Types
+
+| Export                       | Description                                                                                                      |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `IntlayerPluginOptions`      | Options accepted by `intlayer()`. Extends `GetConfigurationOptions` with `compatCallers` and `proxy`.            |
+| `IntlayerProxyPluginOptions` | Options accepted by `intlayerProxy()` and `createIntlayerProxyHandler()`. Includes `ignore` and `configOptions`. |
+| `IntlayerCompilerOptions`    | Options accepted by `intlayerCompiler()`. Includes `configOptions` and `compilerConfig`.                         |
+| `CompatCallerConfig`         | Re-export from `@intlayer/babel`. Describes a compat-adapter caller pattern for field-usage analysis.            |

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

@@ -39,11 +39,126 @@ export default defineConfig({
 });
 ```
 
-## Description
+## Options
 
-The plugin performs the following tasks:
+```ts
+import type { IntlayerPluginOptions } from "vite-intlayer";
+```
+
+`IntlayerPluginOptions` extends `GetConfigurationOptions` (see `@intlayer/config`) with the following additional fields:
+
+| Option          | Type                            | Default     | Description                                                                                                                           |
+| --------------- | ------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `compatCallers` | `CompatCallerConfig[]`          | `[]`        | Extra caller patterns for compat-adapter packages (e.g. `@intlayer/react-i18next`). Passed to the field-usage analyser at build time. |
+| `proxy`         | `{ ignore?: (req) => boolean }` | `undefined` | Options forwarded to the bundled locale-routing proxy. Use `ignore` to exclude specific paths (e.g. API routes) from locale routing.  |
+
+All other options (`override`, `configFile`, …) are forwarded directly to `getConfiguration()`.
+
+### Examples
+
+#### Ignore API routes from locale routing
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
+});
+```
+
+#### With a custom config file path
+
+```ts
+export default defineConfig({
+  plugins: [
+    intlayer({
+      configFile: "./config/intlayer.config.ts",
+    }),
+  ],
+});
+```
+
+#### With compat-adapter callers
+
+```ts
+import { intlayer } from "vite-intlayer";
+import { reactI18nextCallerConfig } from "@intlayer/react-i18next/plugin";
+
+export default defineConfig({
+  plugins: [
+    intlayer({
+      compatCallers: [reactI18nextCallerConfig],
+    }),
+  ],
+});
+```
+
+## What the plugin does
+
+### 1. Dictionary preparation
+
+Before the build starts (and once per hour in dev), `intlayer` calls `prepareIntlayer` to compile all `.content.ts` files into optimised JSON dictionaries stored in `.intlayer/`.
+
+### 2. Module aliases
+
+The plugin adds Vite resolve aliases so that `import { myDict } from 'intlayer/dictionaries/my-dict'` resolves to the compiled JSON file on disk. SSR builds use `ssr.noExternal` to ensure all `@intlayer/*` packages are bundled with aliases applied.
+
+### 3. Dev-server watcher
+
+In development mode a `chokidar` watcher is started. When a `.content.ts` file changes the dictionaries are recompiled and Vite's HMR propagates the update to the browser.
+
+### 4. Bundled locale-routing proxy (v9+)
+
+Since Intlayer v9 the `intlayerProxy` middleware is registered automatically inside `intlayer()`. It handles:
+
+- Locale detection from URL prefix, cookies, and `Accept-Language` header.
+- 301 redirects when the detected locale does not match the current URL.
+- Internal URL rewrites so the framework sees the correct `[locale]` route parameter.
+
+The proxy is controlled by `routing.enableProxy` (default `true`) in your Intlayer config. To disable it completely:
+
+```ts
+// intlayer.config.ts
+import { defineConfig } from "intlayer";
+
+export default defineConfig({
+  routing: { enableProxy: false },
+});
+```
+
+To customise proxy behaviour without a separate `intlayerProxy()` call, pass `proxy` options to the main plugin:
+
+```ts
+intlayer({ proxy: { ignore: (req) => req.url?.startsWith("/api") } });
+```
+
+See the [intlayerProxy documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/vite-intlayer/intlayerProxy.md) for the full routing behaviour reference.
+
+### 5. Bundled compiler (v9+)
+
+When `compiler.enabled` is `true` **and** `compiler.output` is set in your Intlayer config, `intlayer()` registers `intlayerCompiler` automatically. The compiler extracts inline content declarations written directly inside component files and writes them to dictionaries at transform time. See [intlayerCompiler documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/vite-intlayer/intlayerCompiler.md).
+
+### 6. Build optimisations
+
+During a production build the plugin adds:
+
+- **intlayerOptimize** – Babel transform that rewrites `useIntlayer('key')` → `useDictionary(hash)` and injects direct JSON imports.
+- **intlayerPrune** – removes unused content fields from dictionary JSON.
+- **intlayerMinify** – compacts dictionary JSON and optionally mangles field names.
+
+These are inactive in development mode.
+
+## Deprecated aliases
 
-1. **Prepare Dictionaries**: It compiles the dictionaries into optimised files at the start of the build or development process.
-2. **Watch Mode**: In development mode, it watches for changes in dictionary files and recompiles them automatically.
-3. **Aliases**: It provides aliases for accessing the dictionaries in your application.
-4. **Tree-shaking**: It supports tree-shaking of unused translations through the `intlayerPrune` plugin.
+| Deprecated export | Replacement |
+| ----------------- | ----------- |
+| `intlayerPlugin`  | `intlayer`  |
+| `intLayerPlugin`  | `intlayer`  |

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

@@ -30,16 +30,89 @@ The `intlayerPrune` Vite plugin is used to tree-shake and prune unused dictionar
 
 ## Usage
 
+### As part of `intlayer()` (recommended)
+
+Enable pruning through your Intlayer config and the main plugin handles everything:
+
+```ts
+// intlayer.config.ts
+import { defineConfig } from "intlayer";
+
+export default defineConfig({
+  build: {
+    optimize: true, // enables both prune and minify
+  },
+});
+```
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+### Standalone
+
+If you are composing the plugin stack manually, `intlayerPrune` and `intlayerMinify` share a `PruneContext` object that must be created once and passed to both:
+
 ```ts
 // vite.config.ts
 import { defineConfig } from "vite";
-import { intlayer, intlayerPrune } from "vite-intlayer";
+import { intlayerPrune, intlayerMinify } from "vite-intlayer";
+import { createPruneContext } from "@intlayer/babel";
+import { getConfiguration } from "@intlayer/config/node";
+
+const intlayerConfig = getConfiguration();
+const pruneContext = createPruneContext();
 
 export default defineConfig({
-  plugins: [intlayer(), intlayerPrune()],
+  plugins: [
+    intlayerPrune(intlayerConfig, pruneContext),
+    intlayerMinify(intlayerConfig, pruneContext), // optional, reads from same context
+  ],
 });
 ```
 
-## Description
+## How it works
+
+### 1. Usage analysis (buildStart)
+
+During `buildStart`, the `intlayerOptimize` plugin (also part of `intlayer()`) scans every component source file listed in `build.filesList`. For each `useIntlayer('key')` or `getIntlayer('key')` call, it records exactly which fields are accessed, e.g.:
+
+```ts
+const { title, description } = useIntlayer("myDict");
+// records: myDict → { title, description }
+```
+
+This builds `pruneContext.fieldUsageMap` before any `transform` calls run.
+
+### 2. JSON pruning (transform, enforce: 'pre')
+
+When Vite processes a compiled dictionary JSON file, `intlayerPrune` intercepts it before Vite's built-in JSON → ESM conversion. It reads the field-usage map from `pruneContext` and removes any content field that is not in the recorded usage set.
+
+Two content shapes are supported:
+
+- **Static dictionaries** — `{ nodeType: "translation", translation: { en: {...}, fr: {...} } }`. Fields are pruned per-locale inside `translation`.
+- **Dynamic (per-locale) dictionaries** — flat `{ fieldA: ..., fieldB: ... }`. Fields are pruned at the top level.
+
+### 3. Edge cases
+
+If a dictionary's content structure cannot be recognised (e.g. an unusual nested shape), it is added to `pruneContext.dictionariesWithEdgeCases` and **left untouched**. A warning is logged. `intlayerMinify` also skips these dictionaries.
+
+### 4. Field-rename map
+
+When pruning succeeds, `intlayerPrune` also writes `pruneContext.dictionaryKeyToFieldRenameMap` — a mapping from original field names to short aliases. `intlayerMinify` reads this map to rename fields in the output JSON, and `intlayerOptimize`'s Babel rename pass updates property accesses in source files accordingly.
+
+## Activation conditions
+
+`intlayerPrune` is active **only** when all of the following are true:
+
+1. The Vite command is `build`.
+2. `build.optimize` is `true` (or `undefined`, which defaults to `true` for builds).
+3. `build.purge` is `true` in your Intlayer config.
 
-The plugin analyses your source code to identify which dictionary keys are actually used. It then removes any unused content from the bundled dictionary files. This is particularly useful for large projects with many dictionaries where only a subset is used on specific pages or in certain components.
+It is automatically **disabled** when `editor.enabled` is `true` because the editor needs the full dictionary content.

package/docs/en-GB/self_hosting.md

@@ -64,6 +64,32 @@ Chromium (used for Puppeteer screenshot generation) is bundled inside the backen
 
 ## Quick start
 
+Pull and run the published image, supplying your MongoDB Atlas credentials and secrets:
+
+```sh
+docker run -d --name intlayer \
+  -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
+```
+
+Then open **http://localhost:3000**.
+
+> The dashboard is served on `localhost`. See [Limitations](#limitations) — custom domains are not supported by the published image.
+
+---
+
+## Quick start
+
 ```sh
 curl -fsSL https://intlayer.org/install.sh | sh
 ```
@@ -99,7 +125,16 @@ Internal ports (mongo, redis) are not exposed to the host by default.
 
 ## Environment variables
 
-The installer generates a ready-to-use `.env`. The table below describes every variable.
+### Required
+
+| Variable               | Example                      | Description                                                                                                                                  |
+| ---------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DB_ID`                | `intlayer`                   | MongoDB Atlas user                                                                                                                           |
+| `DB_MDP`               | _(your password)_            | MongoDB Atlas password                                                                                                                       |
+| `DB_CLUSTER`           | `cluster0.xxxxx.mongodb.net` | MongoDB Atlas cluster host (used in the `mongodb+srv://` URI)                                                                                |
+| `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)) |
 
 ### Required (auto-generated or prompted)
 
@@ -141,6 +176,26 @@ The installer generates a ready-to-use `.env`. The table below describes every v
 
 ---
 
+### Global mailer
+
+By default, all transactional emails are sent through Resend using `RESEND_API_KEY`. Self-hosted deployments can instead route **every** email — including non-organisation emails such as password resets and magic links — through a global mailer configured with environment variables.
+
+Set `MAIL_PROVIDER` to activate it. When unset, the default Resend mailer is used.
+
+| Variable             | Example                        | Description                                                       |
+| -------------------- | ------------------------------ | ----------------------------------------------------------------- |
+| `MAIL_PROVIDER`      | `smtp`                         | Global transport: `smtp` or `resend`. Leave unset to use defaults |
+| `MAIL_FROM`          | `Intlayer <no-reply@acme.com>` | Sender header. Accepts a bare address or `Name <email>` format    |
+| `MAIL_SMTP_HOST`     | `smtp.acme.com`                | SMTP host (required when `MAIL_PROVIDER=smtp`)                    |
+| `MAIL_SMTP_PORT`     | `587`                          | SMTP port (defaults to `587`)                                     |
+| `MAIL_SMTP_SECURE`   | `false`                        | Implicit TLS. Set `true` for port `465`                           |
+| `MAIL_SMTP_USER`     | _(your user)_                  | SMTP username (optional; omit for unauthenticated relays)         |
+| `MAIL_SMTP_PASSWORD` | _(your password)_              | SMTP password                                                     |
+
+> Precedence: an organisation's own mailer (configured from the **Organisation** dashboard) takes priority over the global mailer, which in turn takes priority over the default Resend key.
+
+---
+
 ## Connecting your Intlayer project
 
 Once the stack is running, point your project at the self-hosted backend and dashboard instead of `intlayer.org`.
@@ -259,47 +314,11 @@ docker run --rm \
 
 ---
 
-## Using a reverse proxy (Nginx / Caddy)
-
-For production deployments, place a reverse proxy in front of the app and backend containers instead of exposing them directly.
-
-### Nginx example
-
-```nginx
-server {
-    listen 80;
-    server_name cms.example.com;
-
-    location / {
-        proxy_pass http://localhost:3000;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-    }
-}
+## Limitations
 
-server {
-    listen 80;
-    server_name api.example.com;
-
-    location / {
-        proxy_pass http://localhost:3100;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-    }
-}
-```
-
-Update the following `.env` variables to match your public domains:
-
-```sh
-BACKEND_URL=https://api.example.com
-APP_URL=https://cms.example.com
-DOMAIN=example.com
-VITE_BACKEND_URL=https://api.example.com
-VITE_DOMAIN=example.com
-```
-
-> `VITE_*` variables are baked into the dashboard image at build time. If you change them after the image is built, you need to rebuild the `app` image (`docker compose build app`) or use runtime config injection.
+- **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.
+- **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 organisation can also configure its own SMTP or Resend mailer from the dashboard.
 
 ---
 
@@ -324,14 +343,6 @@ docker compose build app
 docker compose up -d app
 ```
 
-### Email not sending
-
-By default, all outbound email is captured by Mailpit. Open `http://localhost:8025` to see sent messages. To send real email, set `MAIL_PROVIDER=resend` and `RESEND_API_KEY=<your-key>` in `.env`, then restart the backend:
-
-```sh
-docker compose restart backend
-```
-
 ### MinIO bucket missing
 
 If the `minio-init` one-shot service didn't run (or ran before MinIO was ready), create the bucket manually: