@intlayer/docs 9.4.0-canary.0 → 9.4.0

package/docs/en-GB/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-GB/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-GB/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 recognised 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-GB/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-GB/packages/intlayer/getDictionaryAsync.md): Counterpart for per-locale loader maps.
+- [`useDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/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-GB/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 optimisation
+  - Intlayer
+  - intlayer
+  - Internationalisation
+  - 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-GB/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-GB/packages/intlayer/getIntlayerAsync.md), not this function. The [build plugins](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/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-GB/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-GB/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-GB/packages/intlayer/getDictionary.md): Synchronous counterpart taking a full dictionary.
+- [Dynamic dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/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>
+  >
+>;
+```

package/docs/en-GB/packages/intlayer/getEnumeration.md

@@ -31,6 +31,8 @@ author: aymericzip
 
 The `getEnumeration` function retrieves content corresponding to a specific quantity based on predefined conditions in an enumeration object. The conditions are defined as keys, and their priority is determined by their order in the object.
 
+For more details on how to declare enumerations, see the [Enumeration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/enumeration.md).
+
 ## Parameters
 
 - `enumerationContent: QuantityContent<Content>`

package/docs/en-GB/packages/intlayer/getIntlayer.md

@@ -0,0 +1,196 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: getIntlayer Function Documentation | intlayer
+description: See how to use the getIntlayer function for intlayer package
+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
+---
+
+# Documentation: `getIntlayer` Function in `intlayer`
+
+## Description
+
+The `getIntlayer` function picks one dictionary by its key and returns its content interpreted for a given locale. It is the framework-agnostic counterpart of the `useIntlayer` hook: same content, same selectors, but usable anywhere a React context is not available — Node scripts, server functions, route loaders, metadata builders, Express/Fastify handlers, tests.
+
+It reads the dictionaries generated by Intlayer in `.intlayer/`, so the `key` argument is typed and autocompleted from your own content declarations, and the returned object is fully typed down to each leaf.
+
+**Key Features:**
+
+- Typed dictionary keys and typed returned content
+- Interprets every content node (`t()`, `enu()`, `cond()`, `insert()`, `nest()`, `md()`, `html()`, `file()`, `gender()`)
+- Accepts a locale or a selector object (collections, variants)
+- Results are memoized per `key + locale + selector`
+- Falls back to a safe proxy in development when a dictionary is missing, instead of crashing
+
+---
+
+## Function Signature
+
+```typescript
+getIntlayer(
+  key: DictionaryKeys,                        // Required
+  localeOrSelector?: LocalesValues | DictionarySelector, // Optional
+  plugins?: Plugins[]                         // Optional
+): DeepTransformContent<...>
+```
+
+---
+
+## Parameters
+
+- `key: DictionaryKeys`
+  - **Description**: The key of the dictionary to read, as declared in your content files.
+  - **Type**: `DictionaryKeys` — a union of every declared dictionary key.
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: The locale to interpret the content with, or a selector object for [dynamic dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dynamic_dictionaries/index.md).
+    - `'fr'` — a locale
+    - `{ item: 2 }` — a [collection](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dynamic_dictionaries/collections.md) item (omit `item` to get every item as an array)
+    - `{ variant: 'black-friday' }` — a named [variant](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dynamic_dictionaries/variants.md) (omit for the `default` one)
+    - `{ variant: { id: 'prod_abc', userId: '123' } }` — a structured variant
+    - Any selector can carry a locale: `{ item: 2, locale: 'fr' }`
+  - **Type**: `LocalesValues | DictionarySelector`
+  - **Required**: No (Optional) — defaults to the configured `defaultLocale`.
+
+- `plugins: Plugins[]`
+  - **Description**: Custom node transformers replacing the base interpreter plugins. Advanced use only; omit it to keep the default behaviour.
+  - **Type**: `Plugins[]`
+  - **Required**: No (Optional)
+
+### Returns
+
+- **Type**: The interpreted content of the dictionary, typed from your declaration.
+- **Description**: A plain object mirroring the `content` field of your dictionary, where every Intlayer node has been resolved to its final value for the requested locale.
+
+---
+
+## Example Usage
+
+### Basic Usage
+
+```typescript fileName="src/app.content.ts" codeFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const appContent = {
+  key: "app",
+  content: {
+    title: t({
+      en: "Hello",
+      fr: "Bonjour",
+    }),
+  },
+} satisfies Dictionary;
+
+export default appContent;
+```
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getIntlayer } from "intlayer";
+
+const { title } = getIntlayer("app", "fr"); // "Bonjour"
+```
+
+### Without a locale
+
+Omitting the locale interprets the content with the `defaultLocale` declared in your [configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md).
+
+```typescript
+import { getIntlayer } from "intlayer";
+
+const { title } = getIntlayer("app"); // Interpreted with the default locale
+```
+
+### Inside a 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 });
+};
+```
+
+### With a selector (collections and variants)
+
+```typescript
+import { getIntlayer } from "intlayer";
+
+// A single collection item
+const secondPost = getIntlayer("blog-post", { item: 2, locale: "fr" });
+
+// Every item of the collection, as an ordered array
+const allPosts = getIntlayer("blog-post", { locale: "fr" });
+
+// A named variant
+const banner = getIntlayer("banner", { variant: "black-friday", locale: "fr" });
+```
+
+---
+
+## Behaviour Notes
+
+### Caching
+
+Results are memoised in a module-level cache keyed by `key + locale + selector`. Calling `getIntlayer("app", "fr")` repeatedly interprets the dictionary once and returns the very same object afterwards.
+
+### Missing dictionaries
+
+In development, requesting a key that has no generated dictionary logs a warning once and returns a safe fallback proxy: reading `content.title` yields the string `"app.title"` instead of throwing. This keeps a page usable while the missing declaration is fixed. Run the Intlayer build (or the dev server) so the dictionary is generated.
+
+### Bundle size
+
+`getIntlayer` reads the merged dictionary, which holds **every** locale. In client bundles, the [build plugins](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/bundle_optimization.md) rewrite the call so only the required content is shipped. When you read content outside of rendering (metadata, loaders, server functions) and want a single locale loaded on demand, use [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/intlayer/getIntlayerAsync.md) instead.
+
+---
+
+## Related Functions
+
+- [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/intlayer/getIntlayerAsync.md): Async counterpart loading a single locale chunk.
+- [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/intlayer/getDictionary.md): Interprets a dictionary object you pass yourself, instead of one looked up by key.
+- [`useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/react-intlayer/useIntlayer.md): The React hook equivalent, reading the locale from the 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/en-GB/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: `getIntlayerAsync` Function in `intlayer`
+
+## Description
+
+The `getIntlayerAsync` function picks one dictionary by its key and resolves its content for a given locale, **loading that locale alone**.
+
+It is the asynchronous counterpart of [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/intlayer/getIntlayer.md), meant for the places a dictionary is read outside of rendering — route `head` / metadata builders, loaders, server functions.
+
+Where `getIntlayer` pulls in the merged dictionary holding every locale, the [build plugins](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/bundle_optimization.md) (`@intlayer/babel`, `@intlayer/swc`) rewrite this call into `getDictionaryAsync(loaderMap, key, locale)`, pointing it at the per-locale chunks in `.intlayer/dynamic_dictionaries/`. The bundle therefore only ever carries the locale actually requested.
+
+Without those plugins — an unoptimised build — the call resolves through the synchronous dictionary registry instead: the same content, without the per-locale split.
+
+**Key Features:**
+
+- Same typed keys, selectors and returned content as `getIntlayer`
+- Loads only the requested locale chunk in optimised builds
+- Concurrent calls for the same chunk share a single load
+- Safe to use in `async` metadata builders, loaders and server functions
+
+---
+
+## Function Signature
+
+```typescript
+getIntlayerAsync(
+  key: DictionaryKeys,                        // Required
+  localeOrSelector?: LocalesValues | DictionarySelector, // Optional
+  plugins?: Plugins[]                         // Optional
+): Promise<DeepTransformContent<...>>
+```
+
+---
+
+## Parameters
+
+- `key: DictionaryKeys`
+  - **Description**: The key of the dictionary to read, as declared in your content files.
+  - **Type**: `DictionaryKeys` — a union of every declared dictionary key.
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: The locale to interpret the content with, or a selector object for [dynamic dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dynamic_dictionaries/index.md).
+    - `'fr'` — a locale
+    - `{ item: 2 }` — a [collection](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dynamic_dictionaries/collections.md) item (omit `item` to get every item as an array)
+    - `{ variant: 'black-friday' }` — a named [variant](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dynamic_dictionaries/variants.md) (omit for the `default` one)
+    - `{ variant: { id: 'prod_abc', userId: '123' } }` — a structured variant
+    - Any selector can carry a locale: `{ item: 2, locale: 'fr' }`
+  - **Type**: `LocalesValues | DictionarySelector`
+  - **Required**: No (Optional) — defaults to the configured `defaultLocale`.
+
+- `plugins: Plugins[]`
+  - **Description**: Custom node transformers replacing the base interpreter plugins. Advanced use only.
+  - **Type**: `Plugins[]`
+  - **Required**: No (Optional)
+
+### Returns
+
+- **Type**: `Promise<Content>` — a promise resolving to the interpreted content of the dictionary, typed from your declaration.
+
+---
+
+## Example Usage
+
+### Basic Usage
+
+```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/en-GB/packages/intlayer/getIntlayer.md) | `getIntlayerAsync`                                |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
+| Returns            | The content                                                                                                        | A promise of the content                          |
+| Dictionary loaded  | The merged dictionary (all locales)                                                                                | The chunk of the requested locale only            |
+| Best suited for    | Rendering, synchronous code paths                                                                                  | Metadata, loaders, server functions               |
+| Requires a plugin? | No                                                                                                                 | No — the per-locale split needs the build plugins |
+
+Both accept the same arguments and return the same content: switching from one to the other only changes **when** and **how much** is loaded.
+
+---
+
+## Related Functions
+
+- [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/intlayer/getIntlayer.md): Synchronous equivalent reading the merged dictionary.
+- [`getDictionaryAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/intlayer/getDictionaryAsync.md): The lower-level function the build plugins rewrite this call into.
+- [`getLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/intlayer/getLocale.md): Detects the locale of an incoming request.
+
+---
+
+## 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>
+  >
+>;
+```