@intlayer/docs 9.4.0-canary.0 → 9.4.0

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

@@ -0,0 +1,134 @@
+---
+createdAt: 2026-08-24
+updatedAt: 2026-08-24
+title: elysia-intlayer Package Documentation
+description: Elysia plugin for Intlayer, providing translation functions and locale detection.
+keywords:
+  - elysia-intlayer
+  - elysia
+  - plugin
+  - internationalization
+  - i18n
+slugs:
+  - doc
+  - packages
+  - elysia-intlayer
+  - exports
+history:
+  - version: 9.4.0
+    date: 2026-08-24
+    changes: "Unified documentation for all exports"
+author: aymericzip
+---
+
+# elysia-intlayer Package
+
+The `elysia-intlayer` package provides a plugin for Elysia applications to handle internationalization. It detects the user's locale and injects an `intlayer` object into the route context.
+
+## Installation
+
+```bash packageManager="npm"
+npm install intlayer elysia-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer elysia-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add intlayer elysia-intlayer
+```
+
+```bash packageManager="bun"
+bun add intlayer elysia-intlayer
+```
+
+> `elysia` is a peer dependency (`>=1.0.0`). Elysia targets the **Bun** runtime.
+
+## Exports
+
+### Plugin
+
+Import:
+
+```ts
+import { intlayer } from "elysia-intlayer";
+```
+
+| Function   | Description                                                                                                                                                                                                                                                                                                                  | Related Doc                                                                                                    |
+| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `intlayer` | Elysia plugin that integrates Intlayer into your Elysia application. Handles locale detection from storage (cookie, header) then from `Accept-Language`, injects an `intlayer` object exposing `locale`, `t`, `getIntlayer` and `getDictionary` into the route context, and sets up the `AsyncLocalStorage` request context. | [intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/elysia-intlayer/intlayer.md) |
+
+### Functions
+
+Import:
+
+```ts
+import { t, getIntlayer, getDictionary } from "elysia-intlayer";
+```
+
+| Function        | Description                                                                                                                                                                                                                                                             | Related Doc                                                                                            |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `t`             | Global translation function that retrieves content for the current locale in Elysia. Uses `AsyncLocalStorage` to access the request context set up by the `intlayer` plugin, and falls back to the default locale outside of it. Can also be accessed via `intlayer.t`. | [translation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/translation.md) |
+| `getIntlayer`   | Retrieves a dictionary by its key from the generated declaration and returns its content for the current locale. Optimized version of `getDictionary`. Uses `AsyncLocalStorage` to access the request context. Can also be accessed via `intlayer.getIntlayer`.         | -                                                                                                      |
+| `getDictionary` | Processes dictionary objects and returns content for the current locale. Processes `t()` translations, enumerations, markdown, HTML, etc. Uses `AsyncLocalStorage` to access the request context. Can also be accessed via `intlayer.getDictionary`.                    | -                                                                                                      |
+
+### Types
+
+Import:
+
+```ts
+import type { IntlayerContext, TranslateFunction } from "elysia-intlayer";
+```
+
+| Type                | Description                                                                                                                                                            |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `IntlayerContext`   | Shape of the `intlayer` object injected into every route context: `locale`, `locale_storage`, `locale_detected`, `defaultLocale`, `t`, `getIntlayer`, `getDictionary`. |
+| `TranslateFunction` | Signature of the translation function, translating a locale map into the content matching the current request locale.                                                  |
+
+## Usage
+
+```ts fileName="src/index.ts"
+import { Elysia } from "elysia";
+import { getDictionary, getIntlayer, intlayer, t } from "elysia-intlayer";
+import dictionaryExample from "./index.content";
+
+const app = new Elysia()
+  // Load the internationalization plugin
+  .use(intlayer())
+  // Read the locale and the helpers from the route context
+  .get("/", ({ intlayer }) => ({
+    locale: intlayer!.locale,
+    greeting: intlayer!.t({
+      en: "Hello",
+      fr: "Bonjour",
+      es: "Hola",
+    }),
+    content: intlayer!.getIntlayer("index").exampleOfContent,
+  }))
+  // Or use the standalone helpers, bound to the current request
+  .get("/t_example", () =>
+    t({
+      en: "Example of returned content in English",
+      fr: "Exemple de contenu renvoyé en français",
+      es: "Ejemplo de contenido devuelto en español",
+    })
+  )
+  .get("/getIntlayer_example", () => getIntlayer("index").exampleOfContent)
+  .get(
+    "/getDictionary_example",
+    () => getDictionary(dictionaryExample).exampleOfContent
+  )
+  .listen(3000);
+
+console.log(
+  `🦊 Elysia is running at ${app.server?.hostname}:${app.server?.port}`
+);
+```
+
+> The plugin registers its context through a **global** `derive`, which Elysia types as `Partial<{ intlayer: IntlayerContext }>`. The value is always present at runtime for routes registered after `.use(intlayer())`, so use the non-null assertion (`intlayer!.locale`) — or optional chaining — to satisfy TypeScript in `strict` mode.
+
+## Related Doc
+
+- [Translate your Elysia backend website using Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_elysia.md)
+- [Configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md)

package/docs/en/packages/elysia-intlayer/intlayer.md

@@ -0,0 +1,137 @@
+---
+createdAt: 2026-08-24
+updatedAt: 2026-08-24
+title: intlayer Elysia Plugin Documentation | elysia-intlayer
+description: See how to use the intlayer plugin for elysia-intlayer package
+keywords:
+  - intlayer
+  - elysia
+  - plugin
+  - Intlayer
+  - Internationalization
+  - Documentation
+slugs:
+  - doc
+  - packages
+  - elysia-intlayer
+  - intlayer
+history:
+  - version: 9.4.0
+    date: 2026-08-24
+    changes: "Init doc"
+author: aymericzip
+---
+
+# intlayer Elysia Plugin Documentation
+
+The `intlayer` plugin for Elysia detects the user's locale and injects an `intlayer` object into the route context. It also enables the use of the standalone translation functions within the request context.
+
+## Usage
+
+```ts fileName="src/index.ts"
+import { Elysia } from "elysia";
+import { intlayer } from "elysia-intlayer";
+
+const app = new Elysia().use(intlayer()).get("/", ({ intlayer }) =>
+  intlayer!.t({
+    en: "Hello",
+    fr: "Bonjour",
+    es: "Hola",
+  })
+);
+```
+
+> The plugin registers its context through a **global** `derive`, which Elysia types as `Partial<{ intlayer: IntlayerContext }>`. The value is always present at runtime for routes registered after `.use(intlayer())`, so use the non-null assertion (`intlayer!.t`) — or optional chaining — to satisfy TypeScript in `strict` mode.
+
+The same helpers are available as standalone exports, so you can call them without destructuring the route context:
+
+```ts fileName="src/index.ts"
+import { Elysia } from "elysia";
+import { intlayer, t } from "elysia-intlayer";
+
+const app = new Elysia().use(intlayer()).get("/", () =>
+  t({
+    en: "Hello",
+    fr: "Bonjour",
+    es: "Hola",
+  })
+);
+```
+
+## Description
+
+The plugin performs the following tasks:
+
+1. **Locale Detection**: It reads the locale explicitly set by the client from storage (cookie, header), then falls back to the locale negotiated from the `Accept-Language` header. If no supported locale matches, it falls back to the configured `defaultLocale`.
+2. **Context Injection**: It adds an `intlayer` property to the Elysia route context (see the table below).
+3. **Context Management**: It uses `AsyncLocalStorage` to manage an asynchronous context, allowing the standalone Intlayer functions (`t`, `getIntlayer`, `getDictionary`) to access the request-specific locale without passing the context object around.
+4. **Dictionary Preparation**: It calls `prepareIntlayer` when the plugin is created, so the dictionaries are built when the app boots.
+
+### Route Context
+
+| Property          | Type                   | Description                                                                                   |
+| ----------------- | ---------------------- | --------------------------------------------------------------------------------------------- |
+| `locale`          | `Locale`               | The locale to use for this request. `locale_storage` takes precedence over `locale_detected`. |
+| `locale_storage`  | `Locale` (optional)    | The locale explicitly requested by the client through a cookie or a header.                   |
+| `locale_detected` | `Locale`               | The locale negotiated from the request headers.                                               |
+| `defaultLocale`   | `Locale`               | The locale configured as fallback in `intlayer.config.ts`.                                    |
+| `t`               | `TranslateFunction`    | Translates an inline locale map.                                                              |
+| `getIntlayer`     | `typeof getIntlayer`   | Reads a dictionary by key, defaulting to the request locale.                                  |
+| `getDictionary`   | `typeof getDictionary` | Reads an imported dictionary, defaulting to the request locale.                               |
+
+> Unlike the Node-based Intlayer plugins, `elysia-intlayer` relies on `AsyncLocalStorage` instead of `cls-hooked`, because `cls-hooked` depends on `async_hooks.createHook`, which Bun does not implement.
+
+The request context is released once the response is mapped, so the standalone helpers never resolve against an already terminated request. When called outside of a request handled by the plugin, they fall back to the configured default locale.
+
+## Locale Resolution Order
+
+By default, the plugin resolves the locale in this order:
+
+1. The `INTLAYER_LOCALE` cookie.
+2. The `x-intlayer-locale` header.
+3. The `Accept-Language` header negotiation.
+4. The configured `defaultLocale`.
+
+```bash
+# Negotiated from `Accept-Language`
+curl -H "Accept-Language: fr" http://localhost:3000/
+# Bonjour
+
+# The cookie takes precedence over `Accept-Language`
+curl -H "Accept-Language: fr" -H "Cookie: INTLAYER_LOCALE=es" http://localhost:3000/
+# Hola
+
+# The header takes precedence over `Accept-Language`
+curl -H "Accept-Language: fr" -H "x-intlayer-locale: es" http://localhost:3000/
+# Hola
+```
+
+## Configuration
+
+The plugin reads your `intlayer.config.ts` file. You can customize the cookie and header used for locale detection:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  routing: {
+    storage: [
+      { type: "header", name: "my-locale-header" },
+      { type: "cookie", name: "my-locale-cookie" },
+    ],
+  },
+};
+
+export default config;
+```
+
+> For more information on configuration, visit the [configuration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md).
+
+## Related Doc
+
+- [elysia-intlayer package exports](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/elysia-intlayer/exports.md)
+- [Translate your Elysia backend website using Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_elysia.md)

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

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-01-21
-updatedAt: 2026-01-21
+updatedAt: 2026-08-23
 title: intlayer Package Documentation
 description: The core package of Intlayer, providing the base functions and types for internationalization.
 keywords:
@@ -14,6 +14,9 @@ slugs:
   - intlayer
   - exports
 history:
+  - version: 9.4.0
+    date: 2026-08-23
+    changes: "Document getIntlayer, getIntlayerAsync, getDictionary and getDictionaryAsync"
   - version: 9.0.0
     date: 2026-06-23
     changes: "Add comparePaths utility"
@@ -89,19 +92,21 @@ Import:
 import "intlayer";
 ```
 
-| Function                 | Type       | Description                                                                                                       | Related Doc                                                                                            |
-| ------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `t` / `getTranslation`   | `Function` | Picks content based on the current locale.                                                                        | [translation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/translation.md) |
-| `enu` / `getEnumeration` | `Function` | Picks content based on a quantity.                                                                                | [enumeration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/enumeration.md) |
-| `cond` / `getCondition`  | `Function` | Picks content based on a boolean condition.                                                                       | [condition](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/condition.md)     |
-| `gender`                 | `Function` | Picks content based on a gender.                                                                                  | [gender](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/gender.md)           |
-| `insert`                 | `Function` | Inserts values into a content string.                                                                             | [insertion](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/insertion.md)     |
-| `nest` / `getNesting`    | `Function` | Nests another dictionary.                                                                                         | [nesting](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/nesting.md)         |
-| `md`                     | `Function` | Processes markdown content.                                                                                       | [markdown](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/markdown.md)       |
-| `html`                   | `Function` | Processes HTML content.                                                                                           | [html](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/html.md)               |
-| `file`                   | `Function` | Handles file content.                                                                                             | [file](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/file.md)               |
-| `getDictionary`          | `Function` | Processes objects that look like dictionaries (key, content). It processes `t()` translations, enumerations, etc. | -                                                                                                      |
-| `getIntlayer`            | `Function` | Based on `getDictionary`, but injects an optimized version of the dictionary from the generated declaration.      | -                                                                                                      |
+| Function                 | Type       | Description                                                                                                       | Related Doc                                                                                                                 |
+| ------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `t` / `getTranslation`   | `Function` | Picks content based on the current locale.                                                                        | [translation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/translation.md)                      |
+| `enu` / `getEnumeration` | `Function` | Picks content based on a quantity.                                                                                | [enumeration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/enumeration.md)                      |
+| `cond` / `getCondition`  | `Function` | Picks content based on a boolean condition.                                                                       | [condition](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/condition.md)                          |
+| `gender`                 | `Function` | Picks content based on a gender.                                                                                  | [gender](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/gender.md)                                |
+| `insert`                 | `Function` | Inserts values into a content string.                                                                             | [insertion](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/insertion.md)                          |
+| `nest` / `getNesting`    | `Function` | Nests another dictionary.                                                                                         | [nesting](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/nesting.md)                              |
+| `md`                     | `Function` | Processes markdown content.                                                                                       | [markdown](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/markdown.md)                            |
+| `html`                   | `Function` | Processes HTML content.                                                                                           | [html](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/html.md)                                    |
+| `file`                   | `Function` | Handles file content.                                                                                             | [file](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/file.md)                                    |
+| `getDictionary`          | `Function` | Processes objects that look like dictionaries (key, content). It processes `t()` translations, enumerations, etc. | [getDictionary](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getDictionary.md)           |
+| `getDictionaryAsync`     | `Function` | Loads a single locale chunk of a dictionary from a per-locale loader map, then processes it.                      | [getDictionaryAsync](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getDictionaryAsync.md) |
+| `getIntlayer`            | `Function` | Based on `getDictionary`, but injects an optimized version of the dictionary from the generated declaration.      | [getIntlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getIntlayer.md)               |
+| `getIntlayerAsync`       | `Function` | Async counterpart of `getIntlayer`, loading only the requested locale. For metadata, loaders, server functions.   | [getIntlayerAsync](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getIntlayerAsync.md)     |
 
 ### Localization Utilities
 

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

@@ -0,0 +1,154 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: getDictionary Function Documentation | intlayer
+description: See how to use the getDictionary function for intlayer package
+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: "Initial documentation"
+author: aymericzip
+---
+
+# Documentation: `getDictionary` Function in `intlayer`
+
+## Description
+
+The `getDictionary` function interprets a dictionary **object you pass yourself** and returns its resolved content for a given locale. It walks the content in a single pass and applies each interpreter plugin as needed, resolving `t()` translations, enumerations, conditions, insertions, nesting, markdown, HTML and file nodes.
+
+Unlike [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getIntlayer.md), which looks a dictionary up by key in the generated registry, `getDictionary` takes the dictionary itself. That makes it the right tool for content built at runtime, fetched from an API or a CMS, or declared inline in a test.
+
+**Key Features:**
+
+- Works with any object following the dictionary structure (`{ key, content }`)
+- Also accepts a qualified dictionary group (collections, variants) together with a selector
+- Fully typed: the returned object mirrors the `content` you passed
+- Accepts custom interpreter plugins
+
+---
+
+## Function Signature
+
+```typescript
+getDictionary(
+  dictionary: Dictionary | QualifiedDictionaryGroup, // Required
+  localeOrSelector?: LocalesValues | DictionarySelector, // Optional
+  plugins?: Plugins[]                                // Optional
+): DeepTransformContent<...>
+```
+
+---
+
+## Parameters
+
+- `dictionary: Dictionary | QualifiedDictionaryGroup`
+  - **Description**: The dictionary (or qualified dictionary group) to interpret.
+  - **Type**: `Dictionary | QualifiedDictionaryGroup`
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: The locale to interpret the content with, or a selector object (`{ item }`, `{ variant }`, optionally with `locale`). See [dynamic dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dynamic_dictionaries/index.md).
+  - **Type**: `LocalesValues | DictionarySelector`
+  - **Required**: No (Optional) — defaults to the configured `defaultLocale`.
+
+- `plugins: Plugins[]`
+  - **Description**: An array of node transformers defining how recognized nodes are interpreted. If omitted, the default set of interpreter plugins is used.
+  - **Type**: `Plugins[]`
+  - **Required**: No (Optional)
+
+### Returns
+
+- **Type**: The interpreted content of the dictionary.
+- **Description**: The `content` you passed, with every Intlayer node resolved for the requested locale. For a collection group without an `item` selector, an ordered array of interpreted entries is returned; `null` is returned when the selector targets nothing.
+
+---
+
+## Example Usage
+
+### Basic Usage
+
+```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"
+```
+
+### Interpreting content fetched at 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");
+```
+
+### With a selector
+
+```typescript
+import { getDictionary } from "intlayer";
+
+// A qualified dictionary group is resolved to a single entry…
+const secondItem = getDictionary(blogPostGroup, { item: 2, locale: "fr" });
+
+// …or to an ordered array when no `item` is given
+const allItems = getDictionary(blogPostGroup, { locale: "fr" });
+```
+
+---
+
+## Related Functions
+
+- [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getIntlayer.md): Same interpretation, but the dictionary is looked up by key in the generated registry.
+- [`getDictionaryAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getDictionaryAsync.md): Counterpart for per-locale loader maps.
+- [`useDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/react-intlayer/useDictionary.md): The React hook equivalent, reading the locale from the 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/en/packages/intlayer/getDictionaryAsync.md

@@ -0,0 +1,166 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: getDictionaryAsync Function Documentation | intlayer
+description: See how to use the getDictionaryAsync function for intlayer package
+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: `getDictionaryAsync` Function in `intlayer`
+
+## Description
+
+The `getDictionaryAsync` function loads a **single locale chunk** of a dictionary and returns its interpreted content.
+
+It is the counterpart of [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getDictionary.md) for the per-locale loader maps emitted in `.intlayer/dynamic_dictionaries/`: instead of receiving a dictionary holding every locale, it receives the loader map and awaits only the chunk the requested locale needs.
+
+> In application code you normally call [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getIntlayerAsync.md), not this function. The [build plugins](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/bundle_optimization.md) rewrite every `getIntlayerAsync('key', locale)` call into a `getDictionaryAsync(loaderMap, 'key', locale)` one. `getDictionaryAsync` is exported for custom loaders and for tooling that builds its own loader maps.
+
+**Key Features:**
+
+- Loads only the locale chunk that is requested
+- Supports plain (`locale → loader`) and qualified (`locale → qualifierId → loader`) loader maps
+- Deduplicates concurrent loads of the same chunk, and caches the resolved content
+- Failed loads are evicted from the cache so a later call retries the chunk
+
+---
+
+## Function Signature
+
+```typescript
+getDictionaryAsync(
+  dictionaryLoaders: PlainDynamicLoaderMap | QualifiedDynamicLoaderMap, // Required
+  key: string,                                           // Required
+  localeOrSelector?: LocalesValues | DictionarySelector, // Optional
+  plugins?: Plugins[]                                    // Optional
+): Promise<DeepTransformContent<...>>
+```
+
+---
+
+## Parameters
+
+- `dictionaryLoaders: PlainDynamicLoaderMap | QualifiedDynamicLoaderMap`
+  - **Description**: The per-locale loader map. Plain maps associate a locale with a loader; qualified maps (used by collections and variants) associate a locale with a qualifier id, then with a loader. For a qualified map, only the chunk(s) the selector targets are loaded.
+  - **Type**: `PlainDynamicLoaderMap<T> | QualifiedDynamicLoaderMap`
+  - **Required**: Yes
+
+- `key: string`
+  - **Description**: The dictionary key, used to namespace the chunk cache.
+  - **Type**: `string`
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: The locale to interpret the content with, or a selector object (`{ item }`, `{ variant }`, optionally with `locale`). See [dynamic dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/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)
+
+### Returns
+
+- **Type**: `Promise<Content>` — a promise resolving to the interpreted content of the loaded chunk.
+- **Description**: Resolves to `null` when the map emits no chunk for the requested locale nor for any of its fallbacks, mirroring how a missing qualified coordinate resolves.
+
+---
+
+## Example Usage
+
+### With a generated loader map
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getDictionaryAsync } from "intlayer";
+import appLoaderMap from "../.intlayer/dynamic_dictionaries/app";
+
+const { title } = await getDictionaryAsync(appLoaderMap, "app", "fr");
+```
+
+### With a custom loader map
+
+```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");
+```
+
+### With a selector on a qualified map
+
+```typescript
+import { getDictionaryAsync } from "intlayer";
+
+const promoBanner = await getDictionaryAsync(bannerLoaderMap, "banner", {
+  variant: "black-friday",
+  locale: "fr",
+});
+```
+
+---
+
+## Behaviour Notes
+
+### Caching and deduplication
+
+The cache stores the **promise** of each `key + locale + selector` triple, so concurrent calls for the same chunk await a single load. A rejected load is removed from the cache, so a failing chunk is retried on the next call instead of replaying the same failure forever.
+
+### Locale fallback
+
+A plain loader map is walked along the same fallback chain as the synchronous mode: the requested locale first, then its fallbacks, then `null` if none emitted a chunk.
+
+---
+
+## Related Functions
+
+- [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getIntlayerAsync.md): The function applications call; build plugins rewrite it into `getDictionaryAsync`.
+- [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getDictionary.md): Synchronous counterpart taking a full dictionary.
+- [Dynamic dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dynamic_dictionaries/index.md): Collections and variants, and the loader maps they generate.
+
+---
+
+## 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>
+  >
+>;
+```