@intlayer/docs 9.4.0-canary.0 → 9.4.1

package/docs/en/packages/intlayer/getIntlayer.md

@@ -0,0 +1,196 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: getIntlayer Function Documentation | intlayer
+description: See how to use the getIntlayer function for intlayer package
+keywords:
+  - getIntlayer
+  - dictionary
+  - content
+  - selector
+  - Intlayer
+  - intlayer
+  - Internationalization
+  - Documentation
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getIntlayer
+history:
+  - version: 9.4.0
+    date: 2026-08-23
+    changes: "Initial documentation"
+author: aymericzip
+---
+
+# Documentation: `getIntlayer` Function in `intlayer`
+
+## Description
+
+The `getIntlayer` function picks one dictionary by its key and returns its content interpreted for a given locale. It is the framework-agnostic counterpart of the `useIntlayer` hook: same content, same selectors, but usable anywhere a React context is not available — Node scripts, server functions, route loaders, metadata builders, Express/Fastify handlers, tests.
+
+It reads the dictionaries generated by Intlayer in `.intlayer/`, so the `key` argument is typed and autocompleted from your own content declarations, and the returned object is fully typed down to each leaf.
+
+**Key Features:**
+
+- Typed dictionary keys and typed returned content
+- Interprets every content node (`t()`, `enu()`, `cond()`, `insert()`, `nest()`, `md()`, `html()`, `file()`, `gender()`)
+- Accepts a locale or a selector object (collections, variants)
+- Results are memoized per `key + locale + selector`
+- Falls back to a safe proxy in development when a dictionary is missing, instead of crashing
+
+---
+
+## Function Signature
+
+```typescript
+getIntlayer(
+  key: DictionaryKeys,                        // Required
+  localeOrSelector?: LocalesValues | DictionarySelector, // Optional
+  plugins?: Plugins[]                         // Optional
+): DeepTransformContent<...>
+```
+
+---
+
+## Parameters
+
+- `key: DictionaryKeys`
+  - **Description**: The key of the dictionary to read, as declared in your content files.
+  - **Type**: `DictionaryKeys` — a union of every declared dictionary key.
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: The locale to interpret the content with, or a selector object for [dynamic dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dynamic_dictionaries/index.md).
+    - `'fr'` — a locale
+    - `{ item: 2 }` — a [collection](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dynamic_dictionaries/collections.md) item (omit `item` to get every item as an array)
+    - `{ variant: 'black-friday' }` — a named [variant](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dynamic_dictionaries/variants.md) (omit for the `default` one)
+    - `{ variant: { id: 'prod_abc', userId: '123' } }` — a structured variant
+    - Any selector can carry a locale: `{ item: 2, locale: 'fr' }`
+  - **Type**: `LocalesValues | DictionarySelector`
+  - **Required**: No (Optional) — defaults to the configured `defaultLocale`.
+
+- `plugins: Plugins[]`
+  - **Description**: Custom node transformers replacing the base interpreter plugins. Advanced use only; omit it to keep the default behaviour.
+  - **Type**: `Plugins[]`
+  - **Required**: No (Optional)
+
+### Returns
+
+- **Type**: The interpreted content of the dictionary, typed from your declaration.
+- **Description**: A plain object mirroring the `content` field of your dictionary, where every Intlayer node has been resolved to its final value for the requested locale.
+
+---
+
+## Example Usage
+
+### Basic Usage
+
+```typescript fileName="src/app.content.ts" codeFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const appContent = {
+  key: "app",
+  content: {
+    title: t({
+      en: "Hello",
+      fr: "Bonjour",
+    }),
+  },
+} satisfies Dictionary;
+
+export default appContent;
+```
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getIntlayer } from "intlayer";
+
+const { title } = getIntlayer("app", "fr"); // "Bonjour"
+```
+
+### Without a locale
+
+Omitting the locale interprets the content with the `defaultLocale` declared in your [configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md).
+
+```typescript
+import { getIntlayer } from "intlayer";
+
+const { title } = getIntlayer("app"); // Interpreted with the default locale
+```
+
+### Inside a server handler
+
+```typescript fileName="src/routes/greeting.ts" codeFormat="typescript"
+import { getIntlayer, getLocale } from "intlayer";
+
+export const greetingHandler = async (request: Request) => {
+  const locale = await getLocale({
+    getHeader: (name) => request.headers.get(name) ?? undefined,
+  });
+
+  const { title } = getIntlayer("app", locale);
+
+  return Response.json({ title });
+};
+```
+
+### With a selector (collections and variants)
+
+```typescript
+import { getIntlayer } from "intlayer";
+
+// A single collection item
+const secondPost = getIntlayer("blog-post", { item: 2, locale: "fr" });
+
+// Every item of the collection, as an ordered array
+const allPosts = getIntlayer("blog-post", { locale: "fr" });
+
+// A named variant
+const banner = getIntlayer("banner", { variant: "black-friday", locale: "fr" });
+```
+
+---
+
+## Behaviour Notes
+
+### Caching
+
+Results are memoized in a module-level cache keyed by `key + locale + selector`. Calling `getIntlayer("app", "fr")` repeatedly interprets the dictionary once and returns the very same object afterwards.
+
+### Missing dictionaries
+
+In development, requesting a key that has no generated dictionary logs a warning once and returns a safe fallback proxy: reading `content.title` yields the string `"app.title"` instead of throwing. This keeps a page usable while the missing declaration is fixed. Run the Intlayer build (or the dev server) so the dictionary is generated.
+
+### Bundle size
+
+`getIntlayer` reads the merged dictionary, which holds **every** locale. In client bundles, the [build plugins](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/bundle_optimization.md) rewrite the call so only the required content is shipped. When you read content outside of rendering (metadata, loaders, server functions) and want a single locale loaded on demand, use [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getIntlayerAsync.md) instead.
+
+---
+
+## Related Functions
+
+- [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getIntlayerAsync.md): Async counterpart loading a single locale chunk.
+- [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getDictionary.md): Interprets a dictionary object you pass yourself, instead of one looked up by key.
+- [`useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/react-intlayer/useIntlayer.md): The React hook equivalent, reading the locale from the provider.
+
+---
+
+## TypeScript
+
+```typescript
+function getIntlayer<
+  const T extends DictionaryKeys,
+  const A extends LocalesValues | DictionarySelector = DeclaredLocales,
+>(
+  key: T,
+  localeOrSelector?: A,
+  plugins?: Plugins[]
+): DeepTransformContent<
+  DictionaryRegistryResult<T, A>,
+  IInterpreterPluginState,
+  ExtractSelectorLocale<A>
+>;
+```

package/docs/en/packages/intlayer/getIntlayerAsync.md

@@ -0,0 +1,141 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: getIntlayerAsync Function Documentation | intlayer
+description: See how to use the getIntlayerAsync function for intlayer package
+keywords:
+  - getIntlayerAsync
+  - dictionary
+  - dynamic import
+  - metadata
+  - bundle optimization
+  - Intlayer
+  - intlayer
+  - Internationalization
+  - Documentation
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getIntlayerAsync
+history:
+  - version: 9.4.0
+    date: 2026-08-23
+    changes: "Initial documentation"
+author: aymericzip
+---
+
+# Documentation: `getIntlayerAsync` Function in `intlayer`
+
+## Description
+
+The `getIntlayerAsync` function picks one dictionary by its key and resolves its content for a given locale, **loading that locale alone**.
+
+It is the asynchronous counterpart of [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getIntlayer.md), meant for the places a dictionary is read outside of rendering — route `head` / metadata builders, loaders, server functions.
+
+Where `getIntlayer` pulls in the merged dictionary holding every locale, the [build plugins](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/bundle_optimization.md) (`@intlayer/babel`, `@intlayer/swc`) rewrite this call into `getDictionaryAsync(loaderMap, key, locale)`, pointing it at the per-locale chunks in `.intlayer/dynamic_dictionaries/`. The bundle therefore only ever carries the locale actually requested.
+
+Without those plugins — an unoptimized build — the call resolves through the synchronous dictionary registry instead: the same content, without the per-locale split.
+
+**Key Features:**
+
+- Same typed keys, selectors and returned content as `getIntlayer`
+- Loads only the requested locale chunk in optimized builds
+- Concurrent calls for the same chunk share a single load
+- Safe to use in `async` metadata builders, loaders and server functions
+
+---
+
+## Function Signature
+
+```typescript
+getIntlayerAsync(
+  key: DictionaryKeys,                        // Required
+  localeOrSelector?: LocalesValues | DictionarySelector, // Optional
+  plugins?: Plugins[]                         // Optional
+): Promise<DeepTransformContent<...>>
+```
+
+---
+
+## Parameters
+
+- `key: DictionaryKeys`
+  - **Description**: The key of the dictionary to read, as declared in your content files.
+  - **Type**: `DictionaryKeys` — a union of every declared dictionary key.
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: The locale to interpret the content with, or a selector object for [dynamic dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dynamic_dictionaries/index.md).
+    - `'fr'` — a locale
+    - `{ item: 2 }` — a [collection](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dynamic_dictionaries/collections.md) item (omit `item` to get every item as an array)
+    - `{ variant: 'black-friday' }` — a named [variant](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dynamic_dictionaries/variants.md) (omit for the `default` one)
+    - `{ variant: { id: 'prod_abc', userId: '123' } }` — a structured variant
+    - Any selector can carry a locale: `{ item: 2, locale: 'fr' }`
+  - **Type**: `LocalesValues | DictionarySelector`
+  - **Required**: No (Optional) — defaults to the configured `defaultLocale`.
+
+- `plugins: Plugins[]`
+  - **Description**: Custom node transformers replacing the base interpreter plugins. Advanced use only.
+  - **Type**: `Plugins[]`
+  - **Required**: No (Optional)
+
+### Returns
+
+- **Type**: `Promise<Content>` — a promise resolving to the interpreted content of the dictionary, typed from your declaration.
+
+---
+
+## Example Usage
+
+### Basic Usage
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getIntlayerAsync } from "intlayer";
+
+const { title } = await getIntlayerAsync("app", "fr"); // "Bonjour"
+```
+
+---
+
+## `getIntlayer` vs `getIntlayerAsync`
+
+|                    | [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getIntlayer.md) | `getIntlayerAsync`                                |
+| ------------------ | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| Returns            | The content                                                                                                     | A promise of the content                          |
+| Dictionary loaded  | The merged dictionary (all locales)                                                                             | The chunk of the requested locale only            |
+| Best suited for    | Rendering, synchronous code paths                                                                               | Metadata, loaders, server functions               |
+| Requires a plugin? | No                                                                                                              | No — the per-locale split needs the build plugins |
+
+Both accept the same arguments and return the same content: switching from one to the other only changes **when** and **how much** is loaded.
+
+---
+
+## Related Functions
+
+- [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getIntlayer.md): Synchronous equivalent reading the merged dictionary.
+- [`getDictionaryAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getDictionaryAsync.md): The lower-level function the build plugins rewrite this call into.
+- [`getLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getLocale.md): Detects the locale of an incoming request.
+
+---
+
+## TypeScript
+
+```typescript
+function getIntlayerAsync<
+  const T extends DictionaryKeys,
+  const A extends LocalesValues | DictionarySelector = DeclaredLocales,
+>(
+  key: T,
+  localeOrSelector?: A,
+  plugins?: Plugins[]
+): Promise<
+  DeepTransformContent<
+    DictionaryRegistryResult<T, A>,
+    IInterpreterPluginState,
+    ExtractSelectorLocale<A>
+  >
+>;
+```

package/docs/en/packages/next-intlayer/exports.md

@@ -78,15 +78,16 @@ or
 import "next-intlayer/server";
 ```
 
-| Component                | Description                                                                                                          | Related Doc |
-| ------------------------ | -------------------------------------------------------------------------------------------------------------------- | ----------- |
-| `IntlayerClientProvider` | Provider for client-side components in Next.js App Router. Wraps `IntlayerProvider` from react-intlayer.             | -           |
-| `IntlayerServerProvider` | Provider for server-side components in Next.js (App Router). Provides locale context on the server. (Intlayer < 9.4) | -           |
-| `IntlayerServer`         | Server-side wrapper for Intlayer content in App Router. Ensures proper locale handling in Server Components.         | -           |
-| `HTMLProvider`           | Provider for HTML-related internationalization settings. Allows component overrides for HTML tags.                   | -           |
-| `HTMLRenderer`           | Renders HTML content with custom components.                                                                         | -           |
-| `MarkdownProvider`       | Provider for markdown rendering context. Allows custom component overrides for markdown elements.                    | -           |
-| `MarkdownRenderer`       | Renders markdown content with custom components.                                                                     | -           |
+| Component                | Description                                                                                                                                                                    | Related Doc |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
+| `IntlayerProvider`       | Unified provider for the Next.js App Router. Mounted once in the locale layout, it seeds the request-scoped server context _and_ mounts the client provider. (Intlayer >= 9.4) | -           |
+| `IntlayerClientProvider` | **Deprecated** — use `IntlayerProvider` from `next-intlayer/server`. Provider for client-side components in Next.js App Router. Wraps `IntlayerProvider` from react-intlayer.  | -           |
+| `IntlayerServerProvider` | **Deprecated** — use `IntlayerProvider` from `next-intlayer/server`. Provides locale context on the server. (Intlayer < 9.4)                                                   | -           |
+| `IntlayerServer`         | Server-side wrapper for Intlayer content in App Router. Ensures proper locale handling in Server Components.                                                                   | -           |
+| `HTMLProvider`           | Provider for HTML-related internationalization settings. Allows component overrides for HTML tags.                                                                             | -           |
+| `HTMLRenderer`           | Renders HTML content with custom components.                                                                                                                                   | -           |
+| `MarkdownProvider`       | Provider for markdown rendering context. Allows custom component overrides for markdown elements.                                                                              | -           |
+| `MarkdownRenderer`       | Renders markdown content with custom components.                                                                                                                               | -           |
 
 ### Hooks (Client-side)
 

package/docs/en/packages/next-intlayer/t.md

@@ -167,14 +167,12 @@ In `next-intlayer`, the current locale is managed through context providers: `In
 ```tsx codeFormat={["typescript", "esm", "commonjs"]}
 import type { FC, ReactNode } from "react";
 import type { Locales } from "intlayer";
-import { IntlayerClientProvider } from "next-intlayer";
+import { IntlayerProvider } from "next-intlayer/server";
 
 const Page: FC<{ locale: Locales; children: ReactNode }> = ({
   locale,
   children,
-}) => (
-  <IntlayerClientProvider locale={locale}>{children}</IntlayerClientProvider>
-);
+}) => <IntlayerProvider locale={locale}>{children}</IntlayerProvider>;
 ```
 
  </Tab>

package/docs/en/packages/next-intlayer/useIntlayer.md

@@ -88,8 +88,9 @@ Here's how you can implement the `useIntlayer` hook within a Next.js page to dyn
 ```tsx fileName="src/pages/[locale]/index.tsx" codeFormat={["typescript", "esm"]}
 import { ClientComponentExample } from "@components/ClientComponentExample";
 import { ServerComponentExample } from "@components/ServerComponentExample";
-import { type NextPageIntlayer, IntlayerClientProvider } from "next-intlayer";
+import { type NextPageIntlayer } from "next-intlayer";
 import { useIntlayer } from "next-intlayer";
+import { IntlayerProvider } from "next-intlayer/server";
 
 const HomePage: NextPageIntlayer = async ({ params }) => {
   const { locale } = await params;
@@ -97,13 +98,11 @@ const HomePage: NextPageIntlayer = async ({ params }) => {
   const content = useIntlayer("homepage", locale);
 
   return (
-    <>
+    <IntlayerProvider locale={locale}>
       <p>{content.introduction}</p>
-      <IntlayerClientProvider locale={locale}>
-        <ClientComponentExample />
-      </IntlayerClientProvider>
+      <ClientComponentExample />
       <ServerComponentExample />
-    </>
+    </IntlayerProvider>
   );
 };
 ```

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/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/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:**