@intlayer/docs 9.1.3 → 9.3.0

package/docs/de/intlayer_with_vite+vue.md

@@ -30,9 +30,7 @@ history:
 author: aymericzip
 ---
 
-# Übersetzen Sie Ihre Vite and Vue mit Intlayer | Internationalisierung (i18n)
-
-Siehe [Application Template](https://github.com/aymericzip/intlayer-vite-vue-template) auf GitHub.
+# Übersetzen Sie Ihre Vite- und Vue-Website mit Intlayer | Internationalization (i18n)
 
 ## Inhaltsverzeichnis
 

package/docs/de/live-sync.md

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

package/docs/de/packages/intlayer/getLocalizedUrl.md

@@ -59,36 +59,44 @@ getLocalizedUrl(
 
 ## Parameter
 
-## Beschreibung
-
-Die Funktion `getLocalizedUrl` erzeugt eine lokalisierte URL, indem sie die angegebene URL mit dem spezifizierten Locale voranstellt. Sie verarbeitet sowohl absolute als auch relative URLs und stellt sicher, dass das korrekte Locale-Präfix basierend auf der Konfiguration angewendet wird.
-
----
-
-## Parameter
+### Erforderliche Parameter
 
 - `url: string`
-  - **Beschreibung**: Die ursprüngliche URL-Zeichenkette, die mit einem Locale-Präfix versehen werden soll.
-  - **Typ**: `string`
+  - **Beschreibung**: Die ursprüngliche URL-Zeichenkette, der ein Locale vorangestellt wird.
+  - **Type**: `string`
+  - **Erforderlich**: Ja
 
 - `currentLocale: Locales`
   - **Beschreibung**: Das aktuelle Locale, für das die URL lokalisiert wird.
-  - **Typ**: `Locales`
-
-- `locales: Locales[]`
-  - **Beschreibung**: Optionales Array unterstützter Locales. Standardmäßig werden die im Projekt konfigurierten Locales verwendet.
-  - **Typ**: `Locales[]`
-  - **Standard**: [`Projektkonfiguration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/configuration.md#middleware)
-
-- `defaultLocale: Locales`
-  - **Beschreibung**: Das Standard-Locale für die Anwendung. Standardmäßig wird das konfigurierte Standard-Locale im Projekt verwendet.
-  - **Typ**: `Locales`
-  - **Standard**: [`Projektkonfiguration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/configuration.md#middleware)
-
-- `prefixDefault: boolean`
-  - **Beschreibung**: Ob die URL für das Standard-Locale mit einem Präfix versehen werden soll. Standardmäßig wird der konfigurierte Wert im Projekt verwendet.
-  - **Typ**: `boolean`
-  - **Standard**: [`Projektkonfiguration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/configuration.md#middleware)
+  - **Type**: `Locales`
+  - **Erforderlich**: Ja
+
+### Optionale Parameter
+
+- `options?: object`
+  - **Description**: Konfigurationsobjekt für das URL-Lokalisierungsverhalten.
+  - **Type**: `object`
+  - **Required**: No (Optional)
+
+  - `options.locales?: Locales[]`
+    - **Description**: Array von unterstützten Locales. Falls nicht angegeben, werden die konfigurierten Locales aus Ihrer Projektkonfiguration verwendet.
+    - **Type**: `Locales[]`
+    - **Default**: [`Project Configuration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/configuration.md#middleware)
+
+  - `options.defaultLocale?: Locales`
+    - **Description**: Das Standard-Locale für die Anwendung. Falls nicht angegeben, wird das konfigurierte Standard-Locale aus Ihrer Projektkonfiguration verwendet.
+    - **Type**: `Locales`
+    - **Default**: [`Project Configuration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/configuration.md#middleware)
+
+  - `options.mode?: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'`
+    - **Description**: Der URL-Routing-Modus für die Locale-Verwaltung. Falls nicht angegeben, wird der konfigurierte Modus aus Ihrer Projektkonfiguration verwendet.
+    - **Type**: `'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'`
+    - **Default**: [`Project Configuration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/configuration.md#middleware)
+    - **Modes**:
+      - `prefix-no-default`: Kein Präfix für Standard-Locale, Präfix für alle anderen
+      - `prefix-all`: Präfix für alle Locales einschließlich Standard
+      - `no-prefix`: Kein Locale-Präfix in der URL
+      - `search-params`: Abfrageparameter für Locale verwenden (z. B. `?locale=fr`)
 
 ### Rückgabewert
 

package/docs/de/packages/intlayer/getMultilingualUrls.md

@@ -49,26 +49,12 @@ Die Funktion `getMultilingualUrls` erzeugt eine Zuordnung mehrsprachiger URLs, i
 
 ## Parameter
 
-## Parameter
+### Erforderliche Parameter
 
 - `url: string`
-  - **Beschreibung**: Der ursprüngliche URL-String, der mit Gebietsschemata vorangestellt werden soll.
-  - **Typ**: `string`
-
-- `locales: Locales[]`
-  - **Beschreibung**: Optionale Liste der unterstützten Gebietsschemata. Standardmäßig die im Projekt konfigurierten Gebietsschemata.
-  - **Typ**: `Locales[]`
-  - **Standard**: `localesDefault`
-
-- `defaultLocale: Locales`
-  - **Beschreibung**: Das Standardgebietsschema für die Anwendung. Standardmäßig das im Projekt konfigurierte Standardgebietsschema.
-  - **Typ**: `Locales`
-  - **Standard**: `defaultLocaleDefault`
-
-- `prefixDefault: boolean`
-  - **Beschreibung**: Ob das Standard-Gebietsschema vorangestellt werden soll. Standardmäßig der im Projekt konfigurierte Wert.
-  - **Typ**: `boolean`
-  - **Standard**: `prefixDefaultDefault`
+  - **Description**: Die ursprüngliche URL-Zeichenkette, der Locales vorangestellt werden sollen.
+  - **Type**: `string`
+  - **Required**: Ja
 
 ### Optionale Parameter
 

package/docs/de/packages/react-intlayer/useDictionary.md

@@ -24,12 +24,9 @@ history:
 author: aymericzip
 ---
 
-## Parameter
+# useDictionary Hook Documentation
 
-Der Hook akzeptiert zwei Parameter:
-
-1. **`dictionary`**: Ein deklariertes Wörterbuchobjekt, das lokalisierte Inhalte für bestimmte Schlüssel enthält.
-2. **`locale`** (optional): Die gewünschte Locale. Standardmäßig wird die Locale des aktuellen Kontexts verwendet, wenn keine angegeben ist.
+Der `useDictionary` Hook ermöglicht es dir, ein Objekt zu verarbeiten, das wie ein Dictionary aussieht (mit Schlüsseln und Inhalten), und Übersetzungen, Aufzählungen usw. darin zu handhaben. Im Gegensatz zu `useIntlayer`, das für die Arbeit mit generierten Dictionary-Deklarationen ausgelegt ist, ist `useDictionary` flexibler und kann mit jedem Objekt verwendet werden, das der Dictionary-Struktur folgt.
 
 ## Beispiel für die Verwendung in React
 

package/docs/de/packages/vite-intlayer/exports.md

@@ -48,3 +48,18 @@ import "vite-intlayer";
 | `intlayerProxy`      | Entwicklungs-Middleware-Plugin zur Behandlung der Lokalerkennung und des Routings. | -                                                                                                                      |
 | `intlayerMiddleware` | (**Deprecated**) Alias für `intlayerProxy`.                                        | -                                                                                                                      |
 | `intlayerPrune`      | Plugin, das während des Builds ungenutzte Wörterbücher per Tree-Shaking entfernt.  | [intlayerPrune](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/packages/vite-intlayer/intlayerPrune.md) |
+
+### Utilities
+
+| Export                       | Description                                                                                            | Related Doc                                                                                                            |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
+| `createIntlayerProxyHandler` | Gibt eine Framework-agnostische Node.js `(req, res, next)` Middleware mit Locale-Routing-Logik zurück. | [intlayerProxy](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/packages/vite-intlayer/intlayerProxy.md) |
+
+### Typen
+
+| Export                       | Beschreibung                                                                                                         |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `IntlayerPluginOptions`      | Von `intlayer()` akzeptierte Optionen. Erweitert `GetConfigurationOptions` mit `compatCallers` und `proxy`.          |
+| `IntlayerProxyPluginOptions` | Von `intlayerProxy()` und `createIntlayerProxyHandler()` akzeptierte Optionen. Umfasst `ignore` und `configOptions`. |
+| `IntlayerCompilerOptions`    | Von `intlayerCompiler()` akzeptierte Optionen. Umfasst `configOptions` und `compilerConfig`.                         |
+| `CompatCallerConfig`         | Neu-Export von `@intlayer/babel`. Beschreibt ein compat-adapter caller pattern für die Feldnutzungsanalyse.          |

package/docs/de/packages/vite-intlayer/intlayer.md

@@ -39,11 +39,126 @@ export default defineConfig({
 });
 ```
 
-## Beschreibung
+## Optionen
 
-Das Plugin übernimmt folgende Aufgaben:
+```ts
+import type { IntlayerPluginOptions } from "vite-intlayer";
+```
+
+`IntlayerPluginOptions` erweitert `GetConfigurationOptions` (siehe `@intlayer/config`) mit den folgenden zusätzlichen Feldern:
+
+| Option          | Type                            | Default     | Beschreibung                                                                                                                                                                  |
+| --------------- | ------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `compatCallers` | `CompatCallerConfig[]`          | `[]`        | Zusätzliche Caller-Muster für compat-adapter-Pakete (z. B. `@intlayer/react-i18next`). Wird zur Build-Zeit an den Field-Usage-Analysierer übergeben.                          |
+| `proxy`         | `{ ignore?: (req) => boolean }` | `undefined` | Optionen, die an den gebündelten Locale-Routing-Proxy weitergeleitet werden. Verwenden Sie `ignore`, um bestimmte Pfade (z. B. API-Routen) von Locale-Routing auszuschließen. |
+
+Alle anderen Optionen (`override`, `configFile`, …) werden direkt an `getConfiguration()` weitergeleitet.
+
+### Beispiele
+
+#### API-Routen von der Locale-Routing ignorieren
+
+```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"),
+      },
+    }),
+  ],
+});
+```
+
+#### Mit einem benutzerdefinierten Konfigurationsdateipfad
+
+```ts
+export default defineConfig({
+  plugins: [
+    intlayer({
+      configFile: "./config/intlayer.config.ts",
+    }),
+  ],
+});
+```
+
+#### Mit compat-adapter Aufrufern
+
+```ts
+import { intlayer } from "vite-intlayer";
+import { reactI18nextCallerConfig } from "@intlayer/react-i18next/plugin";
+
+export default defineConfig({
+  plugins: [
+    intlayer({
+      compatCallers: [reactI18nextCallerConfig],
+    }),
+  ],
+});
+```
+
+## Was das Plugin macht
+
+### 1. Dictionary preparation
+
+Vor dem Start des Builds (und einmal pro Stunde in der Entwicklung) ruft `intlayer` `prepareIntlayer` auf, um alle `.content.ts` Dateien in optimierte JSON-Wörterbücher zu kompilieren, die in `.intlayer/` gespeichert werden.
+
+### 2. Module aliases
+
+Das Plugin fügt Vite-Resolve-Aliase hinzu, damit `import { myDict } from 'intlayer/dictionaries/my-dict'` zur kompilierten JSON-Datei auf der Festplatte aufgelöst wird. SSR-Builds verwenden `ssr.noExternal`, um sicherzustellen, dass alle `@intlayer/*`-Packages mit angewendeten Aliasen gebündelt werden.
+
+### 3. Dev-server watcher
+
+Im Entwicklungsmodus wird ein `chokidar` Watcher gestartet. Wenn sich eine `.content.ts` Datei ändert, werden die Wörterbücher neu kompiliert und Vites HMR propagiert das Update zum Browser.
+
+### 4. Bundled locale-routing proxy (v9+)
+
+Seit Intlayer v9 wird die `intlayerProxy` Middleware automatisch innerhalb von `intlayer()` registriert. Sie verwaltet:
+
+- Locale-Erkennung anhand des URL-Präfix, Cookies und `Accept-Language`-Header.
+- 301-Weiterleitungen, wenn die erkannte Locale nicht mit der aktuellen URL übereinstimmt.
+- Interne URL-Umschreibungen, damit das Framework den korrekten `[locale]`-Routenparameter sieht.
+
+Der Proxy wird durch `routing.enableProxy` (Standard `true`) in deiner Intlayer-Konfiguration gesteuert. Um ihn vollständig zu deaktivieren:
+
+```ts
+// intlayer.config.ts
+import { defineConfig } from "intlayer";
+
+export default defineConfig({
+  routing: { enableProxy: false },
+});
+```
+
+Um das Proxy-Verhalten ohne einen separaten `intlayerProxy()`-Aufruf anzupassen, übergebe `proxy`-Optionen an das Haupt-Plugin:
+
+```ts
+intlayer({ proxy: { ignore: (req) => req.url?.startsWith("/api") } });
+```
+
+Siehe die [intlayerProxy-Dokumentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/packages/vite-intlayer/intlayerProxy.md) für die vollständige Routing-Verhaltenreferenz.
+
+### 5. Bundled compiler (v9+)
+
+Wenn `compiler.enabled` auf `true` gesetzt ist **und** `compiler.output` in Ihrer Intlayer-Konfiguration definiert ist, registriert `intlayer()` `intlayerCompiler` automatisch. Der Compiler extrahiert Inline-Content-Deklarationen, die direkt in Komponentendateien geschrieben sind, und schreibt sie zur Transform-Zeit in Dictionaries. Siehe [intlayerCompiler-Dokumentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/packages/vite-intlayer/intlayerCompiler.md).
+
+### 6. Build-Optimierungen
+
+Während eines Production-Builds fügt das Plugin folgende Komponenten hinzu:
+
+- **intlayerOptimize** – Babel-Transformation, die `useIntlayer('key')` → `useDictionary(hash)` umschreibt und direkte JSON-Importe einfügt.
+- **intlayerPrune** – entfernt ungenutzte Content-Felder aus dem Dictionary-JSON.
+- **intlayerMinify** – komprimiert Dictionary-JSON und mangelt optional Feldnamen.
+
+Diese sind im Development-Modus inaktiv.
+
+## Veraltete Aliase
 
-1. **Dictionaries vorbereiten**: Es kompiliert die Dictionaries in optimierte Dateien beim Start des Build- oder Dev-Prozesses.
-2. **Watch-Modus**: Im Entwicklungsmodus überwacht es Änderungen an den Dictionary-Dateien und kompiliert sie automatisch neu.
-3. **Aliases**: Es stellt Aliase zur Verfügung, um in deiner Anwendung auf die Dictionaries zuzugreifen.
-4. **Tree-Shaking**: Es unterstützt Tree-Shaking ungenutzter Übersetzungen über das `intlayerPrune`-Plugin.
+| Veralteter Export | Ersatz     |
+| ----------------- | ---------- |
+| `intlayerPlugin`  | `intlayer` |
+| `intLayerPlugin`  | `intlayer` |

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

@@ -30,16 +30,89 @@ Das `intlayerPrune` Vite-Plugin wird verwendet, um ungenutzte Wörterbücher aus
 
 ## Verwendung
 
+### 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, // aktiviert sowohl Pruning als auch Minifizierung
+  },
+});
+```
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+### Standalone
+
+Wenn Sie den Plugin-Stack manuell zusammenstellen, teilen `intlayerPrune` und `intlayerMinify` ein `PruneContext`-Objekt, das einmal erstellt und an beide übergeben werden muss:
+
 ```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, liest aus demselben Kontext
+  ],
 });
 ```
 
-## Beschreibung
+## Funktionsweise
+
+### 1. Nutzungsanalyse (buildStart)
+
+Während `buildStart` scannt das `intlayerOptimize`-Plugin (auch Teil von `intlayer()`) jede Komponenten-Quelldatei in `build.filesList`. Für jeden `useIntlayer('key')`- oder `getIntlayer('key')`-Aufruf wird genau aufgezeichnet, auf welche Felder zugegriffen wird, z. B.:
+
+```ts
+const { title, description } = useIntlayer("myDict");
+// records: myDict → { title, description }
+```
+
+Dies erstellt `pruneContext.fieldUsageMap`, bevor `transform`-Aufrufe ausgeführt werden.
+
+### 2. JSON Pruning (transform, enforce: 'pre')
+
+Wenn Vite eine kompilierte Dictionary-JSON-Datei verarbeitet, fängt `intlayerPrune` sie vor Vites integrierter JSON → ESM-Konvertierung ab. Es liest die Feldnutzungs-Map aus `pruneContext` und entfernt alle Content-Felder, die nicht im aufgezeichneten Usage-Set enthalten sind.
+
+Zwei Content-Formen werden unterstützt:
+
+- **Static dictionaries** — `{ nodeType: "translation", translation: { en: {...}, fr: {...} } }`. Felder werden pro Locale innerhalb von `translation` entfernt.
+- **Dynamic (per-locale) dictionaries** — flach `{ fieldA: ..., fieldB: ... }`. Felder werden auf oberster Ebene entfernt.
+
+### 3. Edge cases
+
+Falls die Inhaltsstruktur eines Wörterbuchs nicht erkannt werden kann (z. B. eine ungewöhnliche verschachtelte Form), wird sie zu `pruneContext.dictionariesWithEdgeCases` hinzugefügt und **bleibt unverändert**. Eine Warnung wird protokolliert. `intlayerMinify` überspringt diese Wörterbücher ebenfalls.
+
+### 4. Field-rename map
+
+Wenn das Pruning erfolgreich ist, schreibt `intlayerPrune` auch `pruneContext.dictionaryKeyToFieldRenameMap` — eine Zuordnung von ursprünglichen Feldnamen zu kurzen Aliasen. `intlayerMinify` liest diese Map, um Felder in der Ausgabe-JSON umzubenennen, und der Babel-Umbenennungs-Pass von `intlayerOptimize` aktualisiert entsprechend Eigenschaftszugriffe in Quelldateien.
+
+## Aktivierungsbedingungen
+
+`intlayerPrune` ist aktiv **nur** wenn alle folgenden Bedingungen erfüllt sind:
+
+1. Der Vite-Befehl ist `build`.
+2. `build.optimize` ist `true` (oder `undefined`, was standardmäßig `true` für Builds ist).
+3. `build.purge` ist `true` in Ihrer Intlayer-Konfiguration.
 
-Das Plugin analysiert Ihren Quellcode, um zu ermitteln, welche Wörterbuchschlüssel tatsächlich verwendet werden. Anschließend entfernt es nicht verwendete Inhalte aus den gebündelten Wörterbuchdateien. Das ist besonders nützlich bei großen Projekten mit vielen Wörterbüchern, bei denen in bestimmten Seiten oder Komponenten nur ein Teil verwendet wird.
+Es wird automatisch **deaktiviert**, wenn `editor.enabled` `true` ist, da der Editor den vollständigen Dictionary-Inhalt benötigt.

package/docs/de/releases/v9.md

@@ -374,21 +374,6 @@ curl -fsSL https://intlayer.org/install.sh | sh
 
 Das Installationsprogramm lädt eine `docker-compose.yml` und eine `.env` herunter, generiert automatisch die erforderlichen Secrets und führt `docker compose up -d` aus. Alles – das Dashboard, die API, die Datenbank, der Objektspeicher und die transaktionale E-Mail – läuft lokal in Containern.
 
-### Enthaltene Dienste
-
-| Dienst                                  | Zweck                                                                 |
-| --------------------------------------- | --------------------------------------------------------------------- |
-| **app** (TanStack Start)                | Dashboard-Oberfläche auf Port `3000`                                  |
-| **backend** (Fastify/Bun)               | REST API auf Port `3100`                                              |
-| **MongoDB 7** (single-node replica set) | Primäre Datenbank                                                     |
-| **Redis 7**                             | Job-Warteschlangen und Caching                                        |
-| **MinIO**                               | S3-kompatibler Objektspeicher (Avatare, Screenshots)                  |
-| **Mailpit**                             | Lokale SMTP-Senke + Web-UI für transaktionale E-Mails auf Port `8025` |
-
-Chromium (für die Puppeteer-Screenshot-Generierung verwendet) ist im Backend-Image gebündelt – kein zusätzlicher Container erforderlich.
-
----
-
 ## Migrationshinweise von v8
 
 Wenn Sie von v8 upgraden, beachten Sie, dass v9 keine Breaking Changes enthält. Hier sind jedoch die wichtigsten Änderungen:

package/docs/de/self_hosting.md

@@ -80,6 +80,18 @@ Nachdem der Stack gestartet ist, öffnen Sie **http://localhost:3000** und erste
 
 ---
 
+## Erstmalige Einrichtung
+
+Bei einer frischen Instanz (leere Datenbank) leitet Sie das Öffnen des Dashboards zur Seite **`/init`** weiter:
+
+1. Erstellen Sie das erste Konto. Da die users-Collection leer ist, wird dieses Konto automatisch zum **super admin** befördert.
+2. Eine Verifizierungs-E-Mail wird gesendet (über Resend). E-Mail-Verifizierung ist **erforderlich** — deshalb muss `RESEND_API_KEY` vor dem Start gesetzt werden.
+3. Klicken Sie auf den Link in der E-Mail und melden Sie sich an.
+
+Sobald ein Admin existiert, leitet `/init` zur Standard-Anmeldeseite weiter.
+
+---
+
 ## Dienste
 
 | Service     | Image                                | Host port(s)                                   | Zweck                                                     |
@@ -99,7 +111,16 @@ Interne Ports (mongo, redis) werden standardmäßig nicht zum Host exponiert.
 
 ## Umgebungsvariablen
 
-Der Installer generiert eine gebrauchsfertige `.env`. Die folgende Tabelle beschreibt jede Variable.
+### Erforderlich
+
+| Variable               | Beispiel                     | Beschreibung                                                                                                                                                         |
+| ---------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DB_ID`                | `intlayer`                   | MongoDB Atlas Benutzer                                                                                                                                               |
+| `DB_MDP`               | _(dein Passwort)_            | MongoDB Atlas Passwort                                                                                                                                               |
+| `DB_CLUSTER`           | `cluster0.xxxxx.mongodb.net` | MongoDB Atlas Cluster Host (verwendet in der `mongodb+srv://` URI)                                                                                                   |
+| `BETTER_AUTH_SECRET`   | _(generiert)_                | 32-Byte Secret für Session-Signierung                                                                                                                                |
+| `S3_SECRET_ACCESS_KEY` | _(generiert)_                | Secret für das gebündelte MinIO                                                                                                                                      |
+| `RESEND_API_KEY`       | _(dein Schlüssel)_           | Transaktionale E-Mail via Resend. Erforderlich für das erste Setup, es sei denn, du konfigurierst einen globalen SMTP Mailer (siehe [Global mailer](#global-mailer)) |
 
 ### Erforderlich (automatisch generiert oder abgefragt)
 
@@ -141,6 +162,26 @@ Der Installer generiert eine gebrauchsfertige `.env`. Die folgende Tabelle besch
 
 ---
 
+### 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-organization 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 organization's own mailer (configured from the **Organization** dashboard) takes priority over the global mailer, which in turn takes priority over the default Resend key.
+
+---
+
 ## Ihr Intlayer-Projekt verbinden
 
 Sobald der Stack läuft, verweisen Sie Ihr Projekt auf das selbst gehostete Backend und Dashboard anstelle von `intlayer.org`.
@@ -259,47 +300,11 @@ docker run --rm \
 
 ---
 
-## Verwendung eines Reverse-Proxys (Nginx / Caddy)
-
-Für Produktionsbereitstellungen platzieren Sie einen Reverse-Proxy vor den App- und Backend-Containern, anstatt sie direkt zu exponieren.
+## Einschränkungen
 
-### Nginx-Beispiel
-
-```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;
-    }
-}
-
-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;
-    }
-}
-```
-
-Aktualisieren Sie die folgenden `.env`-Variablen, um sie an Ihre öffentlichen Domains anzupassen:
-
-```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_*`-Variablen werden zur Build-Zeit in das Dashboard-Image integriert. Wenn Sie diese nach dem Bau des Images ändern, müssen Sie das `app`-Image neu erstellen (`docker compose build app`) oder die Laufzeitkonfigurationsinjektion verwenden.
+- **MongoDB muss extern sein (Atlas).** Das Backend verbindet sich nur über `mongodb+srv://` (zusammengesetzt aus `DB_ID` / `DB_MDP` / `DB_CLUSTER`), daher kann ein einfaches `mongodb://host:27017` — einschließlich des eigenen `mongod` des Containers — nicht verwendet werden. Stellen Sie einen MongoDB Atlas Cluster bereit.
+- **Keine benutzerdefinierte Domain.** Alle browsergestützten `VITE_*` URLs werden zur Build-Zeit in die App inline eingefügt, und das veröffentlichte Image wird mit `localhost` Werten ausgeliefert. Das Dashboard muss unter `http://localhost:3000` aufgerufen werden; das Serving auf einer öffentlichen Domain würde ein Neubau des Images mit den eingebetteten Ziel-URLs erfordern und wird out-of-the-box nicht unterstützt.
+- **E-Mail erfordert einen funktionierenden Mailer.** Das Setup beim ersten Durchlauf erzwingt eine E-Mail-Verifizierung, daher muss entweder `RESEND_API_KEY` oder ein [globaler SMTP Mailer](#global-mailer) (`MAIL_PROVIDER=smtp` + `MAIL_SMTP_*`) konfiguriert sein. Nach der ersten Anmeldung eines Administrators kann jede Organisation auch ihren eigenen SMTP oder Resend Mailer vom Dashboard aus konfigurieren.
 
 ---
 
@@ -315,15 +320,6 @@ docker compose logs mongo
 docker compose logs redis
 ```
 
-### Dashboard kann die API nicht erreichen
-
-Stellen Sie sicher, dass `VITE_BACKEND_URL` der URL entspricht, unter der das Backend vom **Browser** (nicht vom Docker-Netzwerk) aus erreichbar ist. Wenn Sie den Backend-Port geändert oder einen Reverse-Proxy hinzugefügt haben, erstellen Sie das Dashboard-Image neu:
-
-```sh
-docker compose build app
-docker compose up -d app
-```
-
 ### E-Mail wird nicht gesendet
 
 Standardmäßig werden alle ausgehenden E-Mails von Mailpit abgefangen. Öffnen Sie `http://localhost:8025`, um gesendete Nachrichten anzuzeigen. Um echte E-Mails zu senden, setzen Sie `MAIL_PROVIDER=resend` und `RESEND_API_KEY=<Ihr-Schlüssel>` in `.env` und starten Sie dann das Backend neu: