@intlayer/docs 9.4.0-canary.0 → 9.4.1

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

@@ -0,0 +1,154 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: Documentation de la fonction getDictionary | intlayer
+description: Voir comment utiliser la fonction getDictionary pour le 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: "Documentation initiale"
+author: aymericzip
+---
+
+# Documentation : fonction `getDictionary` dans `intlayer`
+
+## Description
+
+La fonction `getDictionary` interprète un objet dictionnaire **que vous passez vous-même** et retourne son contenu résolu pour une locale donnée. Elle parcourt le contenu en une seule passe et applique chaque plugin interpréteur selon les besoins, en résolvant les traductions `t()`, les énumérations, les conditions, les insertions, l'imbrication, le markdown, le HTML et les nœuds de fichier.
+
+Contrairement à [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/intlayer/getIntlayer.md), qui recherche un dictionnaire par clé dans le registre généré, `getDictionary` prend le dictionnaire lui-même. Cela en fait l'outil idéal pour le contenu construit à l'exécution, récupéré à partir d'une API ou d'un CMS, ou déclaré en ligne dans un test.
+
+**Fonctionnalités clés :**
+
+- Fonctionne avec n'importe quel objet suivant la structure du dictionnaire (`{ key, content }`)
+- Accepte également un groupe de dictionnaire qualifié (collections, variantes) avec un sélecteur
+- Entièrement typé : l'objet retourné reflète le `content` que vous avez passé
+- Accepte les plugins interpréteurs personnalisés
+
+---
+
+## Signature de fonction
+
+```typescript
+getDictionary(
+  dictionary: Dictionary | QualifiedDictionaryGroup, // Requis
+  localeOrSelector?: LocalesValues | DictionarySelector, // Optionnel
+  plugins?: Plugins[]                                // Optionnel
+): DeepTransformContent<...>
+```
+
+---
+
+## Paramètres
+
+- `dictionary: Dictionary | QualifiedDictionaryGroup`
+  - **Description**: Le dictionnaire (ou groupe de dictionnaire qualifié) à interpréter.
+  - **Type**: `Dictionary | QualifiedDictionaryGroup`
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: La locale pour interpréter le contenu avec, ou un objet sélecteur (`{ item }`, `{ variant }`, optionnellement avec `locale`). Voir [dictionnaires dynamiques](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/dynamic_dictionaries/index.md).
+  - **Type**: `LocalesValues | DictionarySelector`
+  - **Required**: No (Optional) — defaults to the configured `defaultLocale`.
+
+- `plugins: Plugins[]`
+  - **Description**: Un tableau de transformateurs de nœuds définissant comment les nœuds reconnus sont interprétés. Si omis, l'ensemble par défaut des plugins d'interprétation est utilisé.
+  - **Type**: `Plugins[]`
+  - **Required**: No (Optional)
+
+### Retours
+
+- **Type** : Le contenu interprété du dictionnaire.
+- **Description** : Le `content` que vous avez transmis, avec chaque nœud Intlayer résolu pour la locale demandée. Pour un groupe de collection sans sélecteur `item`, un tableau ordonné d'entrées interprétées est retourné ; `null` est retourné lorsque le sélecteur ne cible rien.
+
+---
+
+## Exemple d'utilisation
+
+### Utilisation de base
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getDictionary, t } from "intlayer";
+
+const content = getDictionary(
+  {
+    key: "my_key",
+    content: {
+      greeting: t({
+        fr: "Bonjour",
+        en: "Hello",
+      }),
+    },
+  },
+  "fr"
+);
+
+console.log(content.greeting); // "Bonjour"
+```
+
+### Interprétation du contenu récupéré à l'exécution
+
+```typescript
+import { getDictionary, type Dictionary } from "intlayer";
+
+const remoteDictionary: Dictionary = await fetch("/api/cms/banner").then(
+  (res) => res.json()
+);
+
+const banner = getDictionary(remoteDictionary, "fr");
+```
+
+### Avec un sélecteur
+
+```typescript
+import { getDictionary } from "intlayer";
+
+// Un groupe de dictionnaire qualifié est résolu en une seule entrée…
+const secondItem = getDictionary(blogPostGroup, { item: 2, locale: "fr" });
+
+// …ou en un tableau ordonné quand aucun `item` n'est fourni
+const allItems = getDictionary(blogPostGroup, { locale: "fr" });
+```
+
+---
+
+## Fonctions Associées
+
+- [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/intlayer/getIntlayer.md): Même interprétation, mais le dictionnaire est recherché par clé dans le registre généré.
+- [`getDictionaryAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/intlayer/getDictionaryAsync.md): Équivalent pour les cartes de chargeurs par locale.
+- [`useDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/react-intlayer/useDictionary.md): L'équivalent du hook React, lisant la locale depuis le fournisseur.
+
+---
+
+## 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/fr/packages/intlayer/getDictionaryAsync.md

@@ -0,0 +1,166 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: Documentation de la fonction getDictionaryAsync | intlayer
+description: Découvrez comment utiliser la fonction getDictionaryAsync du 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 : fonction `getDictionaryAsync` dans `intlayer`
+
+## Description
+
+La fonction `getDictionaryAsync` charge un **chunk de locale unique** d'un dictionnaire et retourne son contenu interprété.
+
+C'est l'équivalent de [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/intlayer/getDictionary.md) pour les maps de loaders par locale émis dans `.intlayer/dynamic_dictionaries/` : au lieu de recevoir un dictionnaire contenant chaque locale, elle reçoit la map de loader et attend uniquement le chunk dont la locale demandée a besoin.
+
+> Dans le code de l'application, vous appelez normalement [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/intlayer/getIntlayerAsync.md), et non cette fonction. Les [plugins de build](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/bundle_optimization.md) réécrivent chaque appel `getIntlayerAsync('key', locale)` en `getDictionaryAsync(loaderMap, 'key', locale)`. `getDictionaryAsync` est exportée pour les loaders personnalisés et pour les outils qui construisent leurs propres maps de loader.
+
+**Fonctionnalités clés :**
+
+- Charge uniquement le chunk de locale qui est demandé
+- Supporte les maps de loaders simples (`locale → loader`) et qualifiées (`locale → qualifierId → loader`)
+- Déduplique les chargements concurrents du même chunk et met en cache le contenu résolu
+- Les chargements échoués sont évincés du cache afin qu'un appel ultérieur relance le chunk
+
+---
+
+## Signature de fonction
+
+```typescript
+getDictionaryAsync(
+  dictionaryLoaders: PlainDynamicLoaderMap | QualifiedDynamicLoaderMap, // Requis
+  key: string,                                           // Requis
+  localeOrSelector?: LocalesValues | DictionarySelector, // Optionnel
+  plugins?: Plugins[]                                    // Optionnel
+): Promise<DeepTransformContent<...>>
+```
+
+---
+
+## Paramètres
+
+- `dictionaryLoaders: PlainDynamicLoaderMap | QualifiedDynamicLoaderMap`
+  - **Description**: La carte des loaders par locale. Les cartes simples associent une locale à un loader ; les cartes qualifiées (utilisées par les collections et les variantes) associent une locale à un id de qualifiant, puis à un loader. Pour une carte qualifiée, seul le ou les chunk(s) ciblé(s) par le sélecteur sont chargés.
+  - **Type**: `PlainDynamicLoaderMap<T> | QualifiedDynamicLoaderMap`
+  - **Required**: Yes
+
+- `key: string`
+  - **Description**: La clé du dictionnaire, utilisée pour namespacecer le cache des chunks.
+  - **Type**: `string`
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: La locale pour interpréter le contenu, ou un objet sélecteur (`{ item }`, `{ variant }`, optionnellement avec `locale`). Voir [dictionnaires dynamiques](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/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)
+
+### Retourne
+
+- **Type**: `Promise<Content>` — une promesse qui se résout au contenu interprété du chunk chargé.
+- **Description**: Se résout à `null` lorsque la map n'émet aucun chunk pour la locale demandée ni pour l'une de ses alternatives, reflétant la façon dont une coordonnée qualifiée manquante se résout.
+
+---
+
+## Exemple d'utilisation
+
+### Avec une carte de chargement générée
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getDictionaryAsync } from "intlayer";
+import appLoaderMap from "../.intlayer/dynamic_dictionaries/app";
+
+const { title } = await getDictionaryAsync(appLoaderMap, "app", "fr");
+```
+
+### Avec une carte de chargeur personnalisée
+
+```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");
+```
+
+### Avec un sélecteur sur une map qualifiée
+
+```typescript
+import { getDictionaryAsync } from "intlayer";
+
+const promoBanner = await getDictionaryAsync(bannerLoaderMap, "banner", {
+  variant: "black-friday",
+  locale: "fr",
+});
+```
+
+---
+
+## Notes sur le comportement
+
+### Mise en cache et déduplication
+
+Le cache stocke la **promise** de chaque triplet `key + locale + selector`, de sorte que les appels concurrents pour le même chunk attendent un seul chargement. Un chargement rejeté est supprimé du cache, donc un chunk défaillant est réessayé lors de l'appel suivant au lieu de rejouer le même échec indéfiniment.
+
+### Fallback de locale
+
+Une carte de chargeur simple est parcourue selon la même chaîne de fallback que le mode synchrone : d'abord la locale demandée, puis ses fallbacks, puis `null` si aucun n'a émis un chunk.
+
+---
+
+## Fonctions associées
+
+- [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/intlayer/getIntlayerAsync.md): La fonction que les applications appellent ; les plugins de build la réécrivent en `getDictionaryAsync`.
+- [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/intlayer/getDictionary.md): Équivalent synchrone prenant un dictionnaire complet.
+- [Dictionnaires dynamiques](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/dynamic_dictionaries/index.md): Collections et variantes, et les cartes de loader qu'elles génèrent.
+
+---
+
+## 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/fr/packages/intlayer/getEnumeration.md

@@ -31,6 +31,8 @@ author: aymericzip
 
 La fonction `getEnumeration` récupère le contenu correspondant à une quantité spécifique en fonction de conditions prédéfinies dans un objet d'énumération. Les conditions sont définies comme des clés, et leur priorité est déterminée par leur ordre dans l'objet.
 
+Pour plus de détails sur la façon de déclarer des énumérations, voir la [documentation Enumeration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/dictionary/enumeration.md).
+
 ## Paramètres
 
 - `enumerationContent: QuantityContent<Content>`

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

@@ -0,0 +1,196 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: Documentation de la fonction getIntlayer | intlayer
+description: Découvrez comment utiliser la fonction getIntlayer pour le 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: "Documentation initiale"
+author: aymericzip
+---
+
+# Documentation : Fonction `getIntlayer` dans `intlayer`
+
+## Description
+
+La fonction `getIntlayer` récupère un dictionnaire par sa clé et retourne son contenu interprété pour une locale donnée. C'est l'équivalent agnostique du framework du hook `useIntlayer` : même contenu, mêmes sélecteurs, mais utilisable n'importe où où un contexte React n'est pas disponible — scripts Node, fonctions serveur, chargeurs de routes, constructeurs de métadonnées, gestionnaires Express/Fastify, tests.
+
+Elle lit les dictionnaires générés par Intlayer dans `.intlayer/`, donc l'argument `key` est typé et autocompléé à partir de vos propres déclarations de contenu, et l'objet retourné est entièrement typé jusqu'à chaque feuille.
+
+**Fonctionnalités principales :**
+
+- Clés de dictionnaire typées et contenu retourné typé
+- Interprète chaque nœud de contenu (`t()`, `enu()`, `cond()`, `insert()`, `nest()`, `md()`, `html()`, `file()`, `gender()`)
+- Accepte une locale ou un objet sélecteur (collections, variantes)
+- Les résultats sont mémorisés par `key + locale + selector`
+- Bascule vers un proxy sûr en développement quand un dictionnaire est manquant, au lieu de planter
+
+---
+
+## Signature de la fonction
+
+```typescript
+getIntlayer(
+  key: DictionaryKeys,                        // Requis
+  localeOrSelector?: LocalesValues | DictionarySelector, // Optionnel
+  plugins?: Plugins[]                         // Optionnel
+): DeepTransformContent<...>
+```
+
+---
+
+## Paramètres
+
+- `key: DictionaryKeys`
+  - **Description**: La clé du dictionnaire à lire, telle que déclarée dans vos fichiers de contenu.
+  - **Type**: `DictionaryKeys` — une union de chaque clé de dictionnaire déclarée.
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: La locale pour interpréter le contenu avec, ou un objet sélecteur pour [les dictionnaires dynamiques](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/dynamic_dictionaries/index.md).
+    - `'fr'` — une locale
+    - `{ item: 2 }` — un élément de [collection](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/dynamic_dictionaries/collections.md) (omettez `item` pour obtenir chaque élément sous forme de tableau)
+    - `{ variant: 'black-friday' }` — une [variante](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/dynamic_dictionaries/variants.md) nommée (omettez pour la variante `default`)
+    - `{ variant: { id: 'prod_abc', userId: '123' } }` — une variante structurée
+    - Tout sélecteur peut porter une locale: `{ item: 2, locale: 'fr' }`
+  - **Type**: `LocalesValues | DictionarySelector`
+  - **Required**: No (Optional) — defaults to the configured `defaultLocale`.
+
+- `plugins: Plugins[]`
+  - **Description**: Des transformateurs de nœuds personnalisés remplaçant les plugins interpréteur de base. Usage avancé uniquement; omettez-le pour conserver le comportement par défaut.
+  - **Type**: `Plugins[]`
+  - **Required**: No (Optional)
+
+### Retours
+
+- **Type** : Le contenu interprété du dictionnaire, typé à partir de votre déclaration.
+- **Description** : Un objet simple miroir du champ `content` de votre dictionnaire, où chaque nœud Intlayer a été résolu à sa valeur finale pour la locale demandée.
+
+---
+
+## Exemple d'utilisation
+
+### Utilisation de base
+
+```typescript fileName="src/app.content.ts" codeFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const appContent = {
+  key: "app",
+  content: {
+    title: t({
+      fr: "Bonjour",
+      en: "Hello",
+    }),
+  },
+} satisfies Dictionary;
+
+export default appContent;
+```
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getIntlayer } from "intlayer";
+
+const { title } = getIntlayer("app", "fr"); // "Bonjour"
+```
+
+### Sans locale
+
+Omettre la locale interprète le contenu avec la `defaultLocale` déclarée dans votre [configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/configuration.md).
+
+```typescript
+import { getIntlayer } from "intlayer";
+
+const { title } = getIntlayer("app"); // Interprété avec la locale par défaut
+```
+
+### À l'intérieur d'un gestionnaire de serveur
+
+```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 });
+};
+```
+
+### Avec un sélecteur (collections et variantes)
+
+```typescript
+import { getIntlayer } from "intlayer";
+
+// Un seul élément de collection
+const secondPost = getIntlayer("blog-post", { item: 2, locale: "fr" });
+
+// Tous les éléments de la collection, sous forme de tableau ordonné
+const allPosts = getIntlayer("blog-post", { locale: "fr" });
+
+// Une variante nommée
+const banner = getIntlayer("banner", { variant: "black-friday", locale: "fr" });
+```
+
+---
+
+## Notes de comportement
+
+### Mise en cache
+
+Les résultats sont mémorisés dans un cache au niveau du module, indexé par `key + locale + selector`. L'appel répété de `getIntlayer("app", "fr")` interprète le dictionnaire une seule fois et retourne le même objet par la suite.
+
+### Dictionnaires manquants
+
+En développement, demander une clé qui n'a pas de dictionnaire généré enregistre un avertissement une seule fois et retourne un proxy de secours sûr : lire `content.title` produit la chaîne `"app.title"` au lieu de lever une exception. Cela maintient une page utilisable pendant que la déclaration manquante est corrigée. Exécutez la construction Intlayer (ou le serveur de développement) afin que le dictionnaire soit généré.
+
+### Taille du bundle
+
+`getIntlayer` lit le dictionnaire fusionné, qui contient **toutes** les locales. Dans les bundles client, les [plugins de build](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/bundle_optimization.md) réécrivent l'appel afin que seul le contenu nécessaire soit livré. Quand vous lisez du contenu en dehors du rendu (métadonnées, loaders, fonctions serveur) et que vous souhaitez charger une seule locale à la demande, utilisez [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/intlayer/getIntlayerAsync.md) à la place.
+
+---
+
+## Fonctions associées
+
+- [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/intlayer/getIntlayerAsync.md): Équivalent asynchrone chargeant un seul chunk de locale.
+- [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/intlayer/getDictionary.md): Interprète un objet dictionnaire que vous transmettez vous-même, au lieu d'un objet recherché par clé.
+- [`useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/react-intlayer/useIntlayer.md): L'équivalent React hook, lisant la locale du 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/fr/packages/intlayer/getIntlayerAsync.md

@@ -0,0 +1,141 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: Documentation de la fonction getIntlayerAsync | intlayer
+description: Découvrez comment utiliser la fonction getIntlayerAsync du package intlayer
+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 : Fonction `getIntlayerAsync` dans `intlayer`
+
+## Description
+
+La fonction `getIntlayerAsync` sélectionne un dictionnaire par sa clé et résout son contenu pour une locale donnée, **en chargeant cette locale seule**.
+
+C'est l'équivalent asynchrone de [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/intlayer/getIntlayer.md), destiné aux endroits où un dictionnaire est lu en dehors du rendu — constructeurs de `head` / métadonnées de route, loaders, fonctions serveur.
+
+Où `getIntlayer` récupère le dictionnaire fusionné contenant chaque locale, les [plugins de build](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/bundle_optimization.md) (`@intlayer/babel`, `@intlayer/swc`) réécrivent cet appel en `getDictionaryAsync(loaderMap, key, locale)`, le pointant vers les chunks par locale dans `.intlayer/dynamic_dictionaries/`. Le bundle ne porte donc que la locale réellement demandée.
+
+Sans ces plugins — une build non optimisée — l'appel se résout à travers le registre de dictionnaire synchrone à la place : le même contenu, sans la division par locale.
+
+**Fonctionnalités clés :**
+
+- Mêmes clés typées, sélecteurs et contenu retourné que `getIntlayer`
+- Charge uniquement le chunk de la locale demandée dans les builds optimisées
+- Les appels concurrents pour le même chunk partagent un seul chargement
+- Sûr à utiliser dans les constructeurs de métadonnées `async`, loaders et fonctions serveur
+
+---
+
+## Signature de fonction
+
+```typescript
+getIntlayerAsync(
+  key: DictionaryKeys,                        // Requis
+  localeOrSelector?: LocalesValues | DictionarySelector, // Optionnel
+  plugins?: Plugins[]                         // Optionnel
+): Promise<DeepTransformContent<...>>
+```
+
+---
+
+## Paramètres
+
+- `key: DictionaryKeys`
+  - **Description**: La clé du dictionnaire à lire, telle que déclarée dans vos fichiers de contenu.
+  - **Type**: `DictionaryKeys` — une union de chaque clé de dictionnaire déclarée.
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: La locale pour interpréter le contenu avec, ou un objet sélecteur pour les [dictionnaires dynamiques](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/dynamic_dictionaries/index.md).
+    - `'fr'` — une locale
+    - `{ item: 2 }` — un élément de [collection](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/dynamic_dictionaries/collections.md) (omettez `item` pour obtenir chaque élément en tant que tableau)
+    - `{ variant: 'black-friday' }` — une [variante](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/dynamic_dictionaries/variants.md) nommée (omettez pour celle par `default`)
+    - `{ variant: { id: 'prod_abc', userId: '123' } }` — une variante structurée
+    - N'importe quel sélecteur peut porter une locale: `{ item: 2, locale: 'fr' }`
+  - **Type**: `LocalesValues | DictionarySelector`
+  - **Required**: No (Optional) — defaults to the configured `defaultLocale`.
+
+- `plugins: Plugins[]`
+  - **Description**: Des transformateurs de nœuds personnalisés remplaçant les plugins d'interpréteur de base. Utilisation avancée uniquement.
+  - **Type**: `Plugins[]`
+  - **Required**: No (Optional)
+
+### Retours
+
+- **Type**: `Promise<Content>` — une promise qui se résout avec le contenu interprété du dictionnaire, typé à partir de votre déclaration.
+
+---
+
+## Exemple d'utilisation
+
+### Utilisation de 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/fr/packages/intlayer/getIntlayer.md) | `getIntlayerAsync`                                          |
+| ------------------ | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
+| Returns            | Le contenu                                                                                                      | Une promesse du contenu                                     |
+| Dictionary loaded  | Le dictionnaire fusionné (toutes les locales)                                                                   | Le chunk de la locale demandée uniquement                   |
+| Best suited for    | Rendu, chemins de code synchrone                                                                                | Métadonnées, loaders, fonctions serveur                     |
+| Requires a plugin? | Non                                                                                                             | Non — la division par locale nécessite les plugins de build |
+
+Both accept the same arguments and return the same content: switching from one to the other only changes **when** and **how much** is loaded.
+
+---
+
+## Fonctions Associées
+
+- [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/intlayer/getIntlayer.md): Équivalent synchrone lisant le dictionnaire fusionné.
+- [`getDictionaryAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/intlayer/getDictionaryAsync.md): La fonction de bas niveau que les plugins de build réécrivent dans cet appel.
+- [`getLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/intlayer/getLocale.md): Détecte la locale d'une requête entrante.
+
+---
+
+## 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>
+  >
+>;
+```