@intlayer/docs 9.1.3 → 9.3.0

package/docs/it/intlayer_with_vite+vue.md

@@ -27,9 +27,7 @@ history:
 author: aymericzip
 ---
 
-# Traduci la tua Vite and Vue con Intlayer | Internazionalizzazione (i18n)
-
-Consulta il [Template dell'Applicazione](https://github.com/aymericzip/intlayer-vite-vue-template) su GitHub.
+# Traduci il tuo sito web Vite e Vue utilizzando Intlayer | Internazionalizzazione (i18n)
 
 ## Tabella dei Contenuti
 

package/docs/it/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/it/packages/intlayer/getLocalizedUrl.md

@@ -59,36 +59,44 @@ getLocalizedUrl(
 
 ## Parametri
 
-## Descrizione
-
-La funzione `getLocalizedUrl` genera un URL localizzato anteponendo all'URL fornito la locale specificata. Gestisce sia URL assoluti che relativi, assicurando che il prefisso della locale corretta venga applicato in base alla configurazione.
-
----
-
-## Parametri
+### Parametri Obbligatori
 
 - `url: string`
-  - **Descrizione**: La stringa URL originale a cui anteporre una locale.
-  - **Tipo**: `string`
+  - **Description**: La stringa URL originale da prefissare con una locale.
+  - **Type**: `string`
+  - **Required**: Yes
 
 - `currentLocale: Locales`
-  - **Descrizione**: La locale corrente per cui l'URL viene localizzato.
-  - **Tipo**: `Locales`
-
-- `locales: Locales[]`
-  - **Descrizione**: Array opzionale delle localizzazioni supportate. Per default, vengono fornite le localizzazioni configurate nel progetto.
-  - **Tipo**: `Locales[]`
-  - **Default**: [`Configurazione del Progetto`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/configuration.md#middleware)
-
-- `defaultLocale: Locales`
-  - **Descrizione**: La locale predefinita per l'applicazione. Per default, viene fornita la locale predefinita configurata nel progetto.
-  - **Tipo**: `Locales`
-  - **Default**: [`Configurazione del Progetto`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/configuration.md#middleware)
-
-- `prefixDefault: boolean`
-  - **Descrizione**: Se anteporre il prefisso all'URL per la locale predefinita. Per default, viene fornito il valore configurato nel progetto.
-  - **Tipo**: `boolean`
-  - **Default**: [`Configurazione del Progetto`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/configuration.md#middleware)
+  - **Description**: La locale corrente per cui l'URL è in corso di localizzazione.
+  - **Type**: `Locales`
+  - **Required**: Yes
+
+### Parametri Opzionali
+
+- `options?: object`
+  - **Description**: Oggetto di configurazione per il comportamento della localizzazione degli URL.
+  - **Type**: `object`
+  - **Required**: No (Opzionale)
+
+  - `options.locales?: Locales[]`
+    - **Description**: Array di locale supportate. Se non fornito, utilizza le locale configurate dalla configurazione del tuo progetto.
+    - **Type**: `Locales[]`
+    - **Default**: [`Project Configuration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/configuration.md#middleware)
+
+  - `options.defaultLocale?: Locales`
+    - **Description**: La locale predefinita per l'applicazione. Se non fornito, utilizza la locale predefinita configurata dalla configurazione del tuo progetto.
+    - **Type**: `Locales`
+    - **Default**: [`Project Configuration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/configuration.md#middleware)
+
+  - `options.mode?: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'`
+    - **Description**: La modalità di routing degli URL per la gestione delle locale. Se non fornito, utilizza la modalità configurata dalla configurazione del tuo progetto.
+    - **Type**: `'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'`
+    - **Default**: [`Project Configuration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/configuration.md#middleware)
+    - **Modes**:
+      - `prefix-no-default`: Nessun prefisso per la locale predefinita, prefisso per tutte le altre
+      - `prefix-all`: Prefisso per tutte le locale inclusa quella predefinita
+      - `no-prefix`: Nessun prefisso di locale nell'URL
+      - `search-params`: Utilizza i parametri di query per la locale (es. `?locale=fr`)
 
 ### Ritorna
 

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

@@ -50,26 +50,12 @@ getMultilingualUrls(
 
 ## Parametri
 
-## Parametri
+### Parametri Richiesti
 
 - `url: string`
-  - **Descrizione**: La stringa URL originale a cui verranno aggiunti i prefissi delle lingue.
-  - **Tipo**: `string`
-
-- `locales: Locales[]`
-  - **Descrizione**: Array opzionale delle lingue supportate. Di default utilizza le lingue configurate nel progetto.
-  - **Tipo**: `Locales[]`
-  - **Predefinito**: `localesDefault`
-
-- `defaultLocale: Locales`
-  - **Descrizione**: La lingua predefinita per l'applicazione. Di default utilizza la lingua predefinita configurata nel progetto.
-  - **Tipo**: `Locales`
-  - **Predefinito**: `defaultLocaleDefault`
-
-- `prefixDefault: boolean`
-  - **Descrizione**: Se aggiungere il prefisso per la lingua predefinita. Di default utilizza il valore configurato nel progetto.
-  - **Tipo**: `boolean`
-  - **Predefinito**: `prefixDefaultDefault`
+  - **Description**: La stringa URL originale da prefissare con i locale.
+  - **Type**: `string`
+  - **Required**: Yes
 
 ### Parametri Opzionali
 

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

@@ -24,6 +24,10 @@ history:
 author: aymericzip
 ---
 
+# Documentazione dell'Hook useDictionary
+
+L'hook `useDictionary` ti consente di elaborare un oggetto che assomiglia a un dizionario (contenente chiavi e contenuto) e gestire traduzioni, enumerazioni, ecc., al suo interno. A differenza di `useIntlayer`, che è progettato per funzionare con dichiarazioni di dizionario generate, `useDictionary` è più flessibile e può essere utilizzato con qualsiasi oggetto che segue la struttura del dizionario.
+
 ## Esempio di utilizzo in React
 
 Di seguito un esempio di come utilizzare l'hook `useDictionary` in un componente React:
@@ -45,27 +49,6 @@ const ComponentExample: FC = () => {
 };
 ```
 
-## Integrazione lato server
-
-Se si utilizza l'hook `useDictionary` al di fuori di `IntlayerProvider`, la localizzazione deve essere fornita esplicitamente come parametro durante il rendering del componente:
-
-```tsx fileName="./ServerComponentExample.tsx" codeFormat={["typescript", "esm"]}
-import type { FC } from "react";
-import { useDictionary } from "react-intlayer/server";
-import clientComponentExampleContent from "./component.content";
-
-const ServerComponentExample: FC<{ locale: string }> = ({ locale }) => {
-  const { content } = useDictionary(clientComponentExampleContent, locale);
-
-  return (
-    <div>
-      <h1>{content.title}</h1>
-      <p>{content.content}</p>
-    </div>
-  );
-};
-```
-
 ## Suggerimenti Aggiuntivi
 
 - **Sicurezza del Tipo**: Usa sempre `Dictionary` per definire i tuoi dizionari per garantire la sicurezza del tipo.

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

@@ -48,3 +48,18 @@ import "vite-intlayer";
 | `intlayerProxy`      | Plugin middleware per lo sviluppo che gestisce il rilevamento della locale e il routing.  | -                                                                                                                      |
 | `intlayerMiddleware` | (**Deprecato**) Alias per `intlayerProxy`.                                                | -                                                                                                                      |
 | `intlayerPrune`      | Plugin per eseguire il tree-shaking e potare i dizionari non utilizzati durante la build. | [intlayerPrune](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/vite-intlayer/intlayerPrune.md) |
+
+### Utilities
+
+| Export                       | Description                                                                                                | Related Doc                                                                                                            |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `createIntlayerProxyHandler` | Restituisce un middleware Node.js `(req, res, next)` agnostico del framework con logica di routing locale. | [intlayerProxy](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/vite-intlayer/intlayerProxy.md) |
+
+### Types
+
+| Export                       | Description                                                                                                         |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `IntlayerPluginOptions`      | Opzioni accettate da `intlayer()`. Estende `GetConfigurationOptions` con `compatCallers` e `proxy`.                 |
+| `IntlayerProxyPluginOptions` | Opzioni accettate da `intlayerProxy()` e `createIntlayerProxyHandler()`. Include `ignore` e `configOptions`.        |
+| `IntlayerCompilerOptions`    | Opzioni accettate da `intlayerCompiler()`. Include `configOptions` e `compilerConfig`.                              |
+| `CompatCallerConfig`         | Re-export da `@intlayer/babel`. Descrive un pattern di caller compat-adapter per l'analisi dell'utilizzo dei campi. |

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

@@ -40,11 +40,126 @@ export default defineConfig({
 });
 ```
 
-## Descrizione
+## Opzioni
 
-Il plugin esegue le seguenti operazioni:
+```ts
+import type { IntlayerPluginOptions } from "vite-intlayer";
+```
+
+`IntlayerPluginOptions` estende `GetConfigurationOptions` (vedi `@intlayer/config`) con i seguenti campi aggiuntivi:
+
+| Opzione         | Tipo                            | Default     | Descrizione                                                                                                                                                       |
+| --------------- | ------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `compatCallers` | `CompatCallerConfig[]`          | `[]`        | Pattern di caller aggiuntivi per i package compat-adapter (es. `@intlayer/react-i18next`). Passati all'analizzatore di utilizzo dei campi al momento della build. |
+| `proxy`         | `{ ignore?: (req) => boolean }` | `undefined` | Opzioni inoltrate al proxy di locale-routing incluso. Usa `ignore` per escludere percorsi specifici (es. rotte API) dal locale routing.                           |
+
+Tutte le altre opzioni (`override`, `configFile`, …) sono inoltrate direttamente a `getConfiguration()`.
+
+### Esempi
+
+#### Ignora le rotte API dal routing locale
+
+```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"),
+      },
+    }),
+  ],
+});
+```
+
+#### Con un percorso file di configurazione personalizzato
+
+```ts
+export default defineConfig({
+  plugins: [
+    intlayer({
+      configFile: "./config/intlayer.config.ts",
+    }),
+  ],
+});
+```
+
+#### Con caller compat-adapter
+
+```ts
+import { intlayer } from "vite-intlayer";
+import { reactI18nextCallerConfig } from "@intlayer/react-i18next/plugin";
+
+export default defineConfig({
+  plugins: [
+    intlayer({
+      compatCallers: [reactI18nextCallerConfig],
+    }),
+  ],
+});
+```
+
+## Cosa fa il plugin
+
+### 1. Preparazione del dizionario
+
+Prima che il build inizi (e una volta all'ora in dev), `intlayer` chiama `prepareIntlayer` per compilare tutti i file `.content.ts` in dizionari JSON ottimizzati memorizzati in `.intlayer/`.
+
+### 2. Alias di moduli
+
+Il plugin aggiunge alias di risoluzione Vite in modo che `import { myDict } from 'intlayer/dictionaries/my-dict'` si risolva nel file JSON compilato su disco. Le build SSR utilizzano `ssr.noExternal` per assicurare che tutti i pacchetti `@intlayer/*` siano raggruppati con gli alias applicati.
+
+### 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. Proxy di routing delle locale bundled (v9+)
+
+Da Intlayer v9 il middleware `intlayerProxy` viene registrato automaticamente all'interno di `intlayer()`. Gestisce:
+
+- Rilevamento della locale dal prefisso URL, dai cookie e dall'header `Accept-Language`.
+- Reindirizzamenti 301 quando la locale rilevata non corrisponde all'URL corrente.
+- Riscritture URL interne in modo che il framework veda il corretto parametro di route `[locale]`.
+
+Il proxy è controllato da `routing.enableProxy` (valore predefinito `true`) nella tua configurazione Intlayer. Per disabilitarlo completamente:
+
+```ts
+// intlayer.config.ts
+import { defineConfig } from "intlayer";
+
+export default defineConfig({
+  routing: { enableProxy: false },
+});
+```
+
+Per personalizzare il comportamento del proxy senza una chiamata `intlayerProxy()` separata, passa le opzioni `proxy` al plugin principale:
+
+```ts
+intlayer({ proxy: { ignore: (req) => req.url?.startsWith("/api") } });
+```
+
+Consulta la [documentazione intlayerProxy](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/vite-intlayer/intlayerProxy.md) per il riferimento completo del comportamento di routing.
+
+### 5. Compiler integrato (v9+)
+
+Quando `compiler.enabled` è `true` **e** `compiler.output` è impostato nella configurazione di Intlayer, `intlayer()` registra `intlayerCompiler` automaticamente. Il compiler estrae le dichiarazioni di contenuto inline scritte direttamente nei file dei componenti e le scrive nei dizionari durante la trasformazione. Vedi la [documentazione di intlayerCompiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/vite-intlayer/intlayerCompiler.md).
+
+### 6. Ottimizzazioni della build
+
+Durante una build di produzione il plugin aggiunge:
+
+- **intlayerOptimize** – trasformazione Babel che riscrive `useIntlayer('key')` → `useDictionary(hash)` e inietta importazioni JSON dirette.
+- **intlayerPrune** – rimuove i campi di contenuto inutilizzati dal JSON del dizionario.
+- **intlayerMinify** – compatta il JSON del dizionario e facoltativamente offusca i nomi dei campi.
+
+Questi sono inattivi in modalità di sviluppo.
+
+## Alias deprecati
 
-1. **Preparazione dei dizionari**: Compila i dizionari in file ottimizzati all'avvio del processo di build o in dev.
-2. **Modalità watch**: In modalità sviluppo, monitora le modifiche ai file dei dizionari e li ricompila automaticamente.
-3. **Alias**: Fornisce alias per accedere ai dizionari nella tua applicazione.
-4. **Tree-shaking**: Supporta il tree-shaking delle traduzioni non utilizzate tramite il plugin `intlayerPrune`.
+| Esportazione deprecata | Sostituzione |
+| ---------------------- | ------------ |
+| `intlayerPlugin`       | `intlayer`   |
+| `intLayerPlugin`       | `intlayer`   |

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

@@ -30,16 +30,89 @@ Il plugin Vite `intlayerPrune` viene utilizzato per eseguire tree-shaking ed eli
 
 ## Utilizzo
 
+### As part of `intlayer()` (recommended)
+
+Abilita il pruning tramite la configurazione di Intlayer e il plugin principale gestisce tutto:
+
+```ts
+// intlayer.config.ts
+import { defineConfig } from "intlayer";
+
+export default defineConfig({
+  build: {
+    optimize: true, // abilita sia prune che minify
+  },
+});
+```
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+### Standalone
+
+Se stai componendo lo stack di plugin manualmente, `intlayerPrune` e `intlayerMinify` condividono un oggetto `PruneContext` che deve essere creato una sola volta e passato a entrambi:
+
 ```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), // opzionale, legge dallo stesso contesto
+  ],
 });
 ```
 
-## Descrizione
+## Come funziona
+
+### 1. Analisi dell'utilizzo (buildStart)
+
+Durante `buildStart`, il plugin `intlayerOptimize` (anche parte di `intlayer()`) scansiona ogni file sorgente del componente elencato in `build.filesList`. Per ogni chiamata `useIntlayer('key')` o `getIntlayer('key')`, registra esattamente quali campi sono accessibili, ad es.:
+
+```ts
+const { title, description } = useIntlayer("myDict");
+// registra: myDict → { title, description }
+```
+
+Questo costruisce `pruneContext.fieldUsageMap` prima che vengano eseguite le chiamate `transform`.
+
+### 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
+
+Se la struttura del contenuto di un dizionario non può essere riconosciuta (ad esempio, una forma nidificata inusuale), viene aggiunta a `pruneContext.dictionariesWithEdgeCases` e **lasciata intatta**. Un avviso viene registrato. `intlayerMinify` salta anche questi dizionari.
+
+### 4. Field-rename map
+
+Quando la potatura ha successo, `intlayerPrune` scrive anche `pruneContext.dictionaryKeyToFieldRenameMap` — una mappatura dai nomi di campo originali agli alias brevi. `intlayerMinify` legge questa mappa per rinominare i campi nel JSON di output, e il pass di ridenominazione Babel di `intlayerOptimize` aggiorna gli accessi alle proprietà nei file sorgente di conseguenza.
+
+## Condizioni di attivazione
+
+`intlayerPrune` è attivo **solo** quando tutte le seguenti condizioni sono vere:
+
+1. Il comando Vite è `build`.
+2. `build.optimize` è `true` (oppure `undefined`, che di default è `true` per i build).
+3. `build.purge` è `true` nella tua configurazione Intlayer.
 
-Il plugin analizza il tuo codice sorgente per identificare quali chiavi del dizionario sono effettivamente utilizzate. Successivamente rimuove qualsiasi contenuto non utilizzato dai file di dizionario inclusi nel bundle. Questo è particolarmente utile per progetti di grandi dimensioni con molti dizionari, dove solo un sottoinsieme viene utilizzato in pagine o componenti specifici.
+È automaticamente **disabilitato** quando `editor.enabled` è `true` perché l'editor necessita del contenuto completo del dizionario.

package/docs/it/releases/v9.md

@@ -374,21 +374,6 @@ curl -fsSL https://intlayer.org/install.sh | sh
 
 Il programma di installazione scarica un `docker-compose.yml` e un `.env`, genera automaticamente i secret necessari ed esegue `docker compose up -d`. Tutto — il dashboard, l'API, il database, l'archiviazione di oggetti e le email transazionali — viene eseguito localmente nei container.
 
-### Servizi inclusi
-
-| Servizio                                | Scopo                                                                         |
-| --------------------------------------- | ----------------------------------------------------------------------------- |
-| **app** (TanStack Start)                | Interfaccia del dashboard sulla porta `3000`                                  |
-| **backend** (Fastify/Bun)               | API REST sulla porta `3100`                                                   |
-| **MongoDB 7** (single-node replica set) | Database principale                                                           |
-| **Redis 7**                             | Code di lavori e caching                                                      |
-| **MinIO**                               | Archiviazione di oggetti compatibile S3 (avatar, screenshot)                  |
-| **Mailpit**                             | Sink SMTP locale + interfaccia web per email transazionali sulla porta `8025` |
-
-Chromium (utilizzato per la generazione di screenshot con Puppeteer) è incluso nell'immagine del backend — nessun container aggiuntivo necessario.
-
----
-
 ## Note di migrazione da v8
 
 Se stai eseguendo l'aggiornamento da v8, nota che la v9 non include breaking changes. Ma ecco le modifiche chiave:

package/docs/it/self_hosting.md

@@ -64,6 +64,32 @@ Chromium (utilizzato per la generazione di screenshot con Puppeteer) è incluso
 
 ## Avvio rapido
 
+Scarica ed esegui l'immagine pubblicata, fornendo le tue credenziali e i segreti di MongoDB Atlas:
+
+```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
+```
+
+Quindi apri **http://localhost:3000**.
+
+> La dashboard è servita su `localhost`. Vedi [Limitazioni](#limitations) — i domini personalizzati non sono supportati dall'immagine pubblicata.
+
+---
+
+## Avvio rapido
+
 ```sh
 curl -fsSL https://intlayer.org/install.sh | sh
 ```
@@ -99,7 +125,16 @@ Le porte interne (mongo, redis) non sono esposte all'host per impostazione prede
 
 ## Variabili d'ambiente
 
-L'installer genera un `.env` pronto all'uso. La tabella seguente descrive ogni variabile.
+### Obbligatorio
+
+| Variabile              | Esempio                      | Descrizione                                                                                                                                                         |
+| ---------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DB_ID`                | `intlayer`                   | Utente MongoDB Atlas                                                                                                                                                |
+| `DB_MDP`               | _(la tua password)_          | Password MongoDB Atlas                                                                                                                                              |
+| `DB_CLUSTER`           | `cluster0.xxxxx.mongodb.net` | Host del cluster MongoDB Atlas (utilizzato nell'URI `mongodb+srv://`)                                                                                               |
+| `BETTER_AUTH_SECRET`   | _(generato)_                 | Secret a 32 byte per la firma delle sessioni                                                                                                                        |
+| `S3_SECRET_ACCESS_KEY` | _(generato)_                 | Secret per il MinIO bundle                                                                                                                                          |
+| `RESEND_API_KEY`       | _(la tua chiave)_            | Email transazionale via Resend. Obbligatorio per la configurazione iniziale a meno che non configuri un mailer SMTP globale (vedi [Mailer globale](#global-mailer)) |
 
 ### Obbligatorie (generate automaticamente o richieste)
 
@@ -141,6 +176,26 @@ L'installer genera un `.env` pronto all'uso. La tabella seguente descrive ogni v
 
 ---
 
+### Mailer globale
+
+Per impostazione predefinita, tutti i messaggi email transazionali vengono inviati tramite Resend utilizzando `RESEND_API_KEY`. I deploy self-hosted possono invece instradare **ogni** email — incluse le email non organizzative come i reset delle password e i magic link — attraverso un mailer globale configurato con variabili di ambiente.
+
+Imposta `MAIL_PROVIDER` per attivarlo. Quando non impostato, viene utilizzato il mailer predefinito di Resend.
+
+| Variabile            | Esempio                        | Descrizione                                                                      |
+| -------------------- | ------------------------------ | -------------------------------------------------------------------------------- |
+| `MAIL_PROVIDER`      | `smtp`                         | Trasporto globale: `smtp` o `resend`. Lascia non impostato per usare i default   |
+| `MAIL_FROM`          | `Intlayer <no-reply@acme.com>` | Intestazione del mittente. Accetta un indirizzo bare o il formato `Name <email>` |
+| `MAIL_SMTP_HOST`     | `smtp.acme.com`                | Host SMTP (obbligatorio quando `MAIL_PROVIDER=smtp`)                             |
+| `MAIL_SMTP_PORT`     | `587`                          | Porta SMTP (per impostazione predefinita `587`)                                  |
+| `MAIL_SMTP_SECURE`   | `false`                        | TLS implicito. Imposta `true` per la porta `465`                                 |
+| `MAIL_SMTP_USER`     | _(il tuo utente)_              | Nome utente SMTP (opzionale; ometti per relay non autenticati)                   |
+| `MAIL_SMTP_PASSWORD` | _(la tua password)_            | Password SMTP                                                                    |
+
+> Precedenza: il mailer personalizzato di un'organizzazione (configurato dal dashboard **Organization**) ha priorità rispetto al mailer globale, che a sua volta ha priorità rispetto alla chiave Resend predefinita.
+
+---
+
 ## Collegamento del tuo progetto Intlayer
 
 Una volta che lo stack è in esecuzione, punta il tuo progetto al backend e alla dashboard self-hosted invece di `intlayer.org`.
@@ -259,47 +314,11 @@ docker run --rm \
 
 ---
 
-## Utilizzo di un reverse proxy (Nginx / Caddy)
-
-Per le implementazioni in produzione, posiziona un reverse proxy davanti ai container dell'app e del backend invece di esporli direttamente.
-
-### Esempio Nginx
-
-```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;
-    }
-}
+## Limitazioni
 
-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;
-    }
-}
-```
-
-Aggiorna le seguenti variabili `.env` per corrispondere ai tuoi domini pubblici:
-
-```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
-```
-
-> Le variabili `VITE_*` sono integrate nell'immagine della dashboard al momento della compilazione. Se le modifichi dopo che l'immagine è stata compilata, devi ricostruire l'immagine `app` (`docker compose build app`) o utilizzare l'iniezione della configurazione a runtime.
+- **MongoDB deve essere esterno (Atlas).** Il backend si connette solo su `mongodb+srv://` (costruito da `DB_ID` / `DB_MDP` / `DB_CLUSTER`), quindi un semplice `mongodb://host:27017` — incluso il `mongod` incluso nel container — non può essere utilizzato. Fornire un cluster MongoDB Atlas.
+- **Nessun dominio personalizzato.** Tutti gli URL `VITE_*` rivolti al browser sono inline nell'app al momento della compilazione, e l'immagine pubblicata contiene valori `localhost`. Il dashboard deve essere accessibile su `http://localhost:3000`; servarlo su un dominio pubblico richiederebbe di ricompilare l'immagine con gli URL di destinazione incorporati e non è supportato out of the box.
+- **Email richiede un mailer funzionante.** La configurazione al primo avvio applica la verifica email, quindi `RESEND_API_KEY` o un [mailer SMTP globale](#global-mailer) (`MAIL_PROVIDER=smtp` + `MAIL_SMTP_*`) deve essere configurato. Dopo che il primo amministratore ha effettuato l'accesso, ogni organizzazione può anche configurare il proprio mailer SMTP o Resend dal dashboard.
 
 ---
 
@@ -324,14 +343,6 @@ docker compose build app
 docker compose up -d app
 ```
 
-### Email non inviate
-
-Per impostazione predefinita, tutte le email in uscita vengono catturate da Mailpit. Apri `http://localhost:8025` per vedere i messaggi inviati. Per inviare email reali, imposta `MAIL_PROVIDER=resend` e `RESEND_API_KEY=<la-tua-chiave>` in `.env`, quindi riavvia il backend:
-
-```sh
-docker compose restart backend
-```
-
 ### Bucket MinIO mancante
 
 Se il servizio one-shot `minio-init` non è stato eseguito (o è stato eseguito prima che MinIO fosse pronto), crea il bucket manualmente: