@intlayer/docs 9.4.0-canary.0 → 9.4.0

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

@@ -0,0 +1,154 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: Documentazione della Funzione getDictionary | intlayer
+description: Scopri come utilizzare la funzione getDictionary per il package intlayer
+keywords:
+  - getDictionary
+  - dictionary
+  - interpreter
+  - content
+  - Intlayer
+  - intlayer
+  - Internationalization
+  - Documentation
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getDictionary
+history:
+  - version: 9.4.0
+    date: 2026-08-23
+    changes: "Documentazione iniziale"
+author: aymericzip
+---
+
+# Documentazione: Funzione `getDictionary` in `intlayer`
+
+## Descrizione
+
+La funzione `getDictionary` interpreta un oggetto dizionario **che passi tu stesso** e restituisce il suo contenuto risolto per una determinata locale. Percorre il contenuto in un singolo passaggio e applica ogni plugin interprete secondo necessità, risolvendo traduzioni `t()`, enumerazioni, condizioni, inserimenti, annidamento, markdown, HTML e nodi di file.
+
+A differenza di [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/intlayer/getIntlayer.md), che cerca un dizionario per chiave nel registro generato, `getDictionary` accetta il dizionario stesso. Questo lo rende lo strumento giusto per contenuti costruiti a runtime, recuperati da un'API o un CMS, o dichiarati inline in un test.
+
+**Caratteristiche principali:**
+
+- Funziona con qualsiasi oggetto che segua la struttura del dizionario (`{ key, content }`)
+- Accetta anche un gruppo di dizionari qualificato (collezioni, varianti) insieme a un selettore
+- Completamente tipizzato: l'oggetto restituito rispecchia il `content` che hai passato
+- Accetta plugin interpreti personalizzati
+
+---
+
+## Function Signature
+
+```typescript
+getDictionary(
+  dictionary: Dictionary | QualifiedDictionaryGroup, // Obbligatorio
+  localeOrSelector?: LocalesValues | DictionarySelector, // Opzionale
+  plugins?: Plugins[]                                // Opzionale
+): DeepTransformContent<...>
+```
+
+---
+
+## Parametri
+
+- `dictionary: Dictionary | QualifiedDictionaryGroup`
+  - **Descrizione**: Il dizionario (o il gruppo di dizionari qualificati) da interpretare.
+  - **Tipo**: `Dictionary | QualifiedDictionaryGroup`
+  - **Richiesto**: Sì
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Descrizione**: La locale per interpretare il contenuto, o un oggetto selettore (`{ item }`, `{ variant }`, opzionalmente con `locale`). Vedi [dizionari dinamici](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dynamic_dictionaries/index.md).
+  - **Tipo**: `LocalesValues | DictionarySelector`
+  - **Richiesto**: No (Opzionale) — predefinito su `defaultLocale` configurato.
+
+- `plugins: Plugins[]`
+  - **Descrizione**: Un array di trasformatori di nodi che definiscono come i nodi riconosciuti vengono interpretati. Se omesso, viene utilizzato il set predefinito di plugin dell'interprete.
+  - **Tipo**: `Plugins[]`
+  - **Richiesto**: No (Opzionale)
+
+### Restituisce
+
+- **Type**: Il contenuto interpretato del dizionario.
+- **Description**: Il `content` che hai passato, con ogni nodo Intlayer risolto per la locale richiesta. Per un gruppo di raccolta senza un selettore `item`, viene restituito un array ordinato di voci interpretate; `null` viene restituito quando il selettore non trova nulla.
+
+---
+
+## Utilizzo di Esempio
+
+### Utilizzo di base
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getDictionary, t } from "intlayer";
+
+const content = getDictionary(
+  {
+    key: "my_key",
+    content: {
+      greeting: t({
+        en: "Hello",
+        fr: "Bonjour",
+      }),
+    },
+  },
+  "fr"
+);
+
+console.log(content.greeting); // "Bonjour"
+```
+
+### Interpretazione del contenuto recuperato a runtime
+
+```typescript
+import { getDictionary, type Dictionary } from "intlayer";
+
+const remoteDictionary: Dictionary = await fetch("/api/cms/banner").then(
+  (res) => res.json()
+);
+
+const banner = getDictionary(remoteDictionary, "fr");
+```
+
+### Con un selettore
+
+```typescript
+import { getDictionary } from "intlayer";
+
+// Un gruppo di dizionario qualificato viene risolto a una singola voce…
+const secondItem = getDictionary(blogPostGroup, { item: 2, locale: "fr" });
+
+// …o a un array ordinato quando nessun `item` è fornito
+const allItems = getDictionary(blogPostGroup, { locale: "fr" });
+```
+
+---
+
+## Funzioni Correlate
+
+- [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/intlayer/getIntlayer.md): Stessa interpretazione, ma il dizionario viene cercato per chiave nel registro generato.
+- [`getDictionaryAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/intlayer/getDictionaryAsync.md): Controparte per mappe di loader per locale.
+- [`useDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/react-intlayer/useDictionary.md): L'equivalente hook React, che legge la locale dal provider.
+
+---
+
+## TypeScript
+
+```typescript
+function getDictionary<
+  const T extends Dictionary | QualifiedDictionaryGroup,
+  const A extends LocalesValues | DictionarySelector = DeclaredLocales,
+>(
+  dictionary: T,
+  localeOrSelector?: A,
+  plugins?: Plugins[]
+): DeepTransformContent<
+  ResolveQualifiedDictionaryContent<T, A>,
+  IInterpreterPluginState,
+  ExtractSelectorLocale<A>
+>;
+```

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

@@ -0,0 +1,166 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: Documentazione della funzione getDictionaryAsync | intlayer
+description: Scopri come utilizzare la funzione getDictionaryAsync del package intlayer
+keywords:
+  - getDictionaryAsync
+  - dictionary
+  - dynamic dictionaries
+  - loader map
+  - bundle optimization
+  - Intlayer
+  - intlayer
+  - Internationalization
+  - Documentation
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getDictionaryAsync
+history:
+  - version: 9.4.0
+    date: 2026-08-23
+    changes: "Initial documentation"
+author: aymericzip
+---
+
+# Documentation: funzione `getDictionaryAsync` in `intlayer`
+
+## Descrizione
+
+La funzione `getDictionaryAsync` carica un **singolo chunk di locale** di un dizionario e restituisce il suo contenuto interpretato.
+
+È l'equivalente di [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/intlayer/getDictionary.md) per le mappe di loader per-locale emesse in `.intlayer/dynamic_dictionaries/`: invece di ricevere un dizionario che contiene ogni locale, riceve la mappa di loader e attende solo il chunk di cui ha bisogno il locale richiesto.
+
+> Nel codice dell'applicazione normalmente chiami [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/intlayer/getIntlayerAsync.md), non questa funzione. I [plugin di build](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/bundle_optimization.md) riscrivono ogni chiamata `getIntlayerAsync('key', locale)` in una `getDictionaryAsync(loaderMap, 'key', locale)`. `getDictionaryAsync` è esportato per custom loader e per strumenti che costruiscono le proprie mappe di loader.
+
+**Caratteristiche principali:**
+
+- Carica solo il chunk di locale richiesto
+- Supporta mappe di loader semplici (`locale → loader`) e qualificate (`locale → qualifierId → loader`)
+- Deduplica i caricamenti concorrenti dello stesso chunk e mette in cache il contenuto risolto
+- I caricamenti non riusciti vengono rimossi dalla cache in modo che una chiamata successiva riprovi il chunk
+
+---
+
+## Firma della Funzione
+
+```typescript
+getDictionaryAsync(
+  dictionaryLoaders: PlainDynamicLoaderMap | QualifiedDynamicLoaderMap, // Obbligatorio
+  key: string,                                           // Obbligatorio
+  localeOrSelector?: LocalesValues | DictionarySelector, // Opzionale
+  plugins?: Plugins[]                                    // Opzionale
+): Promise<DeepTransformContent<...>>
+```
+
+---
+
+## Parametri
+
+- `dictionaryLoaders: PlainDynamicLoaderMap | QualifiedDynamicLoaderMap`
+  - **Description**: La mappa dei loader per locale. Le mappe semplici associano una locale a un loader; le mappe qualificate (utilizzate da collezioni e varianti) associano una locale a un id qualificatore, quindi a un loader. Per una mappa qualificata, vengono caricati solo i chunk che il selettore target.
+  - **Type**: `PlainDynamicLoaderMap<T> | QualifiedDynamicLoaderMap`
+  - **Required**: Yes
+
+- `key: string`
+  - **Description**: La chiave del dizionario, utilizzata per namespace la cache dei chunk.
+  - **Type**: `string`
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: La locale per interpretare il contenuto, oppure un oggetto selettore (`{ item }`, `{ variant }`, opzionalmente con `locale`). Vedi [dynamic dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dynamic_dictionaries/index.md).
+  - **Type**: `LocalesValues | DictionarySelector`
+  - **Required**: No (Optional) — defaults to the configured `defaultLocale`.
+
+- `plugins: Plugins[]`
+  - **Description**: Node transformers. Defaults to the base interpreter set.
+  - **Type**: `Plugins[]`
+  - **Required**: No (Optional)
+
+### Restituzioni
+
+- **Type**: `Promise<Content>` — una promise che si risolve nel contenuto interpretato del chunk caricato.
+- **Description**: Si risolve a `null` quando la mappa non emette alcun chunk per la locale richiesta né per nessuno dei suoi fallback, rispecchiando come una coordinata qualificata mancante si risolve.
+
+---
+
+## Utilizzo di esempio
+
+### Con una mappa di loader generata
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getDictionaryAsync } from "intlayer";
+import appLoaderMap from "../.intlayer/dynamic_dictionaries/app";
+
+const { title } = await getDictionaryAsync(appLoaderMap, "app", "fr");
+```
+
+### Con una mappa di loader personalizzata
+
+```typescript
+import { getDictionaryAsync } from "intlayer";
+
+const loaderMap = {
+  en: () => import("./banner.en.json").then((mod) => mod.default),
+  fr: () => import("./banner.fr.json").then((mod) => mod.default),
+};
+
+const banner = await getDictionaryAsync(loaderMap, "banner", "fr");
+```
+
+### Con un selettore su una mappa qualificata
+
+```typescript
+import { getDictionaryAsync } from "intlayer";
+
+const promoBanner = await getDictionaryAsync(bannerLoaderMap, "banner", {
+  variant: "black-friday",
+  locale: "fr",
+});
+```
+
+---
+
+## Note sul comportamento
+
+### Caching and deduplication
+
+La cache memorizza la **promise** di ogni tripla `key + locale + selector`, quindi le chiamate concorrenti per lo stesso chunk attendono un singolo caricamento. Un caricamento rifiutato viene rimosso dalla cache, quindi un chunk che fallisce viene ritentato alla chiamata successiva invece di riprodurre lo stesso errore per sempre.
+
+### Fallback della locale
+
+Una plain loader map viene attraversata seguendo la stessa fallback chain della modalità sincrona: la locale richiesta per prima, poi i suoi fallback, poi `null` se nessuno ha emesso un chunk.
+
+---
+
+## Funzioni Correlate
+
+- [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/intlayer/getIntlayerAsync.md): La funzione che le applicazioni chiamano; i plugin di build la riscrivono in `getDictionaryAsync`.
+- [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/intlayer/getDictionary.md): Controparte sincrona che accetta un dizionario completo.
+- [Dizionari dinamici](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dynamic_dictionaries/index.md): Collezioni e varianti, e le mappe dei loader che generano.
+
+---
+
+## TypeScript
+
+```typescript
+function getDictionaryAsync<
+  const T extends Dictionary,
+  const A extends LocalesValues | DictionarySelector = DeclaredLocales,
+>(
+  dictionaryLoaders: PlainDynamicLoaderMap<T> | QualifiedDynamicLoaderMap,
+  key: string,
+  localeOrSelector?: A,
+  plugins?: Plugins[]
+): Promise<
+  DeepTransformContent<
+    T["content"],
+    IInterpreterPluginState,
+    ExtractSelectorLocale<A>
+  >
+>;
+```

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

@@ -31,6 +31,8 @@ author: aymericzip
 
 La funzione `getEnumeration` recupera il contenuto corrispondente a una quantità specifica basata su condizioni predefinite in un oggetto di enumerazione. Le condizioni sono definite come chiavi e la loro priorità è determinata dall'ordine nell'oggetto.
 
+Per maggiori dettagli su come dichiarare le enumerazioni, consulta la [documentazione Enumeration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dictionary/enumeration.md).
+
 ## Parametri
 
 - `enumerationContent: QuantityContent<Content>`

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

@@ -0,0 +1,197 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: Documentazione della funzione getIntlayer | intlayer
+description: Scopri come utilizzare la funzione getIntlayer per il package intlayer
+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
+---
+
+# Documentazione: Funzione `getIntlayer` in `intlayer`
+
+## Descrizione
+
+La funzione `getIntlayer` seleziona un dizionario dalla sua chiave e restituisce il suo contenuto interpretato per una determinata locale. È l'equivalente indipendente dal framework dell'hook `useIntlayer`: stesso contenuto, stessi selettori, ma utilizzabile ovunque un contesto React non sia disponibile — script Node, funzioni server, route loader, generatori di metadati, handler Express/Fastify, test.
+
+Legge i dizionari generati da Intlayer in `.intlayer/`, quindi l'argomento `key` è tipizzato e autocompleto dalle tue dichiarazioni di contenuto, e l'oggetto restituito è completamente tipizzato fino a ogni foglia.
+
+**Caratteristiche principali:**
+
+- Chiavi di dizionario tipizzate e contenuto restituito tipizzato
+- Interpreta ogni nodo di contenuto (`t()`, `enu()`, `cond()`, `insert()`, `nest()`, `md()`, `html()`, `file()`, `gender()`)
+- Accetta una locale o un oggetto selettore (collezioni, varianti)
+- I risultati sono memorizzati nella cache per `key + locale + selector`
+- Ricade su un proxy sicuro in sviluppo quando un dizionario è mancante, invece di bloccarsi
+
+---
+
+## Firma della Funzione
+
+```typescript
+getIntlayer(
+  key: DictionaryKeys,                        // Obbligatorio
+  localeOrSelector?: LocalesValues | DictionarySelector, // Opzionale
+  plugins?: Plugins[]                         // Opzionale
+): DeepTransformContent<...>
+```
+
+---
+
+## Parametri
+
+- `key: DictionaryKeys`
+  - **Description**: La chiave del dizionario da leggere, come dichiarato nei tuoi file di contenuto.
+  - **Type**: `DictionaryKeys` — un'unione di ogni chiave di dizionario dichiarata.
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: La locale per interpretare il contenuto con, o un oggetto selettore per [dizionari dinamici](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dynamic_dictionaries/index.md).
+    - `'fr'` — una locale
+    - `{ item: 2 }` — un elemento [collection](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dynamic_dictionaries/collections.md) (ometti `item` per ottenere ogni elemento come array)
+    - `{ variant: 'black-friday' }` — un [variant](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dynamic_dictionaries/variants.md) denominato (ometti per quello `default`)
+    - `{ variant: { id: 'prod_abc', userId: '123' } }` — un variant strutturato
+    - Qualsiasi selettore può portare una locale: `{ item: 2, locale: 'fr' }`
+  - **Type**: `LocalesValues | DictionarySelector`
+  - **Required**: No (Optional) — defaults to the configured `defaultLocale`.
+
+- `plugins: Plugins[]`
+  - **Description**: Custom node transformers che sostituiscono i plugin dell'interprete base. Solo uso avanzato; omettilo per mantenere il comportamento predefinito.
+  - **Type**: `Plugins[]`
+  - **Required**: No (Optional)
+
+### Restituzioni
+
+- **Type**: Il contenuto interpretato del dizionario, tipizzato dalla tua dichiarazione.
+- **Description**: Un oggetto semplice che rispecchia il campo `content` del tuo dizionario, dove ogni nodo Intlayer è stato risolto al suo valore finale per la locale richiesta.
+
+---
+
+## Esempio di utilizzo
+
+### Utilizzo di Base
+
+```typescript fileName="src/app.content.ts" codeFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const appContent = {
+  key: "app",
+  content: {
+    title: t({
+      it: "Ciao",
+      en: "Hello",
+      fr: "Bonjour",
+    }),
+  },
+} satisfies Dictionary;
+
+export default appContent;
+```
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getIntlayer } from "intlayer";
+
+const { title } = getIntlayer("app", "it"); // "Ciao"
+```
+
+### Senza una locale
+
+Omettendo la locale il contenuto viene interpretato con la `defaultLocale` dichiarata nella tua [configurazione](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/configuration.md).
+
+```typescript
+import { getIntlayer } from "intlayer";
+
+const { title } = getIntlayer("app"); // Interpretato con la locale predefinita
+```
+
+### All'interno di un 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 });
+};
+```
+
+### Con un selettore (collezioni e varianti)
+
+```typescript
+import { getIntlayer } from "intlayer";
+
+// Un singolo elemento della collezione
+const secondPost = getIntlayer("blog-post", { item: 2, locale: "fr" });
+
+// Ogni elemento della collezione, come un array ordinato
+const allPosts = getIntlayer("blog-post", { locale: "fr" });
+
+// Una variante denominata
+const banner = getIntlayer("banner", { variant: "black-friday", locale: "fr" });
+```
+
+---
+
+## Note sul comportamento
+
+### Caching
+
+I risultati sono memoizzati in una cache a livello di modulo con chiave `key + locale + selector`. Chiamare `getIntlayer("app", "fr")` ripetutamente interpreta il dizionario una sola volta e restituisce lo stesso oggetto in seguito.
+
+### Dizionari mancanti
+
+Durante lo sviluppo, richiedere una chiave che non ha un dizionario generato registra un avviso una volta e restituisce un proxy di fallback sicuro: leggere `content.title` produce la stringa `"app.title"` invece di generare un errore. Questo mantiene una pagina utilizzabile mentre la dichiarazione mancante viene corretta. Eseguire il build di Intlayer (o il server di sviluppo) affinché il dizionario sia generato.
+
+### Dimensione del bundle
+
+`getIntlayer` legge il dizionario unito, che contiene **ogni** locale. Nei bundle client, i [plugin di build](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/bundle_optimization.md) riscrivono la chiamata in modo che solo il contenuto richiesto venga spedito. Quando leggi contenuto al di fuori del rendering (metadata, loader, funzioni server) e vuoi che una singola locale sia caricata su richiesta, usa invece [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/intlayer/getIntlayerAsync.md).
+
+---
+
+## Funzioni Correlate
+
+- [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/intlayer/getIntlayerAsync.md): Controparte asincrona che carica un singolo chunk di locale.
+- [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/intlayer/getDictionary.md): Interpreta un oggetto dictionary che passi tu stesso, invece di uno cercato per chiave.
+- [`useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/react-intlayer/useIntlayer.md): L'equivalente React hook, che legge il locale dal 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/it/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: funzione `getIntlayerAsync` in `intlayer`
+
+## Descrizione
+
+La funzione `getIntlayerAsync` seleziona un dizionario in base alla sua chiave e risolve il suo contenuto per una determinata locale, **caricando solo quella locale**.
+
+È l'equivalente asincrono di [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/intlayer/getIntlayer.md), destinato ai casi in cui un dizionario viene letto al di fuori del rendering — route `head` / metadata builders, loaders, server functions.
+
+Dove `getIntlayer` carica il dizionario unito contenente ogni locale, i [build plugins](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/bundle_optimization.md) (`@intlayer/babel`, `@intlayer/swc`) riscrivono questa chiamata in `getDictionaryAsync(loaderMap, key, locale)`, puntandola ai chunk per-locale in `.intlayer/dynamic_dictionaries/`. Il bundle quindi contiene solo la locale effettivamente richiesta.
+
+Senza questi plugin — una build non ottimizzata — la chiamata viene risolta attraverso il registro dizionario sincrono invece: lo stesso contenuto, senza la divisione per-locale.
+
+**Caratteristiche principali:**
+
+- Stesse chiavi tipizzate, selettori e contenuto restituito di `getIntlayer`
+- Carica solo il chunk della locale richiesta nelle build ottimizzate
+- Le chiamate concorrenti per lo stesso chunk condividono un singolo caricamento
+- Sicuro da usare in `async` metadata builders, loaders e server functions
+
+---
+
+## Firma della Funzione
+
+```typescript
+getIntlayerAsync(
+  key: DictionaryKeys,                        // Obbligatorio
+  localeOrSelector?: LocalesValues | DictionarySelector, // Opzionale
+  plugins?: Plugins[]                         // Opzionale
+): Promise<DeepTransformContent<...>>
+```
+
+---
+
+## Parametri
+
+- `key: DictionaryKeys`
+  - **Description**: La chiave del dizionario da leggere, come dichiarato nei tuoi file di contenuto.
+  - **Type**: `DictionaryKeys` — un'unione di ogni chiave di dizionario dichiarata.
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: La locale per interpretare il contenuto, o un oggetto selector per [dizionari dinamici](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dynamic_dictionaries/index.md).
+    - `'fr'` — una locale
+    - `{ item: 2 }` — un elemento di [collection](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dynamic_dictionaries/collections.md) (ometti `item` per ottenere ogni elemento come array)
+    - `{ variant: 'black-friday' }` — un [variant](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dynamic_dictionaries/variants.md) denominato (ometti per quello `default`)
+    - `{ variant: { id: 'prod_abc', userId: '123' } }` — una variante strutturata
+    - Qualsiasi selector può contenere una locale: `{ item: 2, locale: 'fr' }`
+  - **Type**: `LocalesValues | DictionarySelector`
+  - **Required**: No (Optional) — defaults to the configured `defaultLocale`.
+
+- `plugins: Plugins[]`
+  - **Description**: Custom node transformers che sostituiscono i plugin base dell'interprete. Uso avanzato soltanto.
+  - **Type**: `Plugins[]`
+  - **Required**: No (Optional)
+
+### Restituisce
+
+- **Type**: `Promise<Content>` — una promise che si risolve nel contenuto interpretato del dizionario, tipizzato dalla tua dichiarazione.
+
+---
+
+## Esempio di utilizzo
+
+### Utilizzo di base
+
+```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/it/packages/intlayer/getIntlayer.md) | `getIntlayerAsync`                                     |
+| ------------------ | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| Returns            | Il contenuto                                                                                                    | Una promise del contenuto                              |
+| Dictionary loaded  | Il dizionario unito (tutte le lingue)                                                                           | Il chunk della lingua richiesta solamente              |
+| Best suited for    | Rendering, percorsi di codice sincroni                                                                          | Metadata, loaders, funzioni server                     |
+| Requires a plugin? | No                                                                                                              | No — la divisione per locale necessita i build plugins |
+
+Entrambi accettano gli stessi argomenti e restituiscono lo stesso contenuto: il cambio da uno all'altro cambia solo **quando** e **quanto** viene caricato.
+
+---
+
+## Funzioni Correlate
+
+- [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/intlayer/getIntlayer.md): Equivalente sincrono che legge il dizionario unito.
+- [`getDictionaryAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/intlayer/getDictionaryAsync.md): La funzione di basso livello in cui i plugin di build riscrivono questa chiamata.
+- [`getLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/intlayer/getLocale.md): Rileva la locale di una richiesta in arrivo.
+
+---
+
+## 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>
+  >
+>;
+```