@intlayer/docs 9.0.0-canary.6 → 9.0.0-canary.8

package/docs/en/packages/vite-intlayer/intlayerProxy.md

@@ -0,0 +1,172 @@
+---
+createdAt: 2026-06-25
+updatedAt: 2026-06-25
+title: intlayerProxy Vite Plugin Documentation | vite-intlayer
+description: Locale-routing middleware for Vite dev/preview servers and production SSR. Handles locale detection, URL redirects, and internal rewrites.
+keywords:
+  - intlayerProxy
+  - vite
+  - plugin
+  - middleware
+  - locale
+  - routing
+  - internationalization
+  - i18n
+  - SSR
+slugs:
+  - doc
+  - packages
+  - vite-intlayer
+  - intlayerProxy
+history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "Merged configOptions into single options object; proxy bundled into intlayer()"
+author: aymericzip
+---
+
+# intlayerProxy
+
+`intlayerProxy` is a Vite plugin that registers locale-routing middleware for **every environment**: dev server, preview server, and production SSR (Nitro / TanStack Start).
+
+> **Since Intlayer v9** `intlayerProxy` is automatically included inside the main [`intlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/vite-intlayer/intlayer.md) plugin and enabled by default via `routing.enableProxy: true`. You only need to register it separately if you need lower-level control or are using it outside the standard `intlayer()` setup.
+
+## Usage
+
+### As part of `intlayer()` (recommended, v9+)
+
+Pass `proxy` options to the main plugin instead of registering `intlayerProxy` separately:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
+});
+```
+
+### Standalone (when needed)
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+## Options
+
+```ts
+import type { IntlayerProxyPluginOptions } from "vite-intlayer";
+```
+
+All options are optional and passed as a single object:
+
+| Option          | Type                                | Description                                                                                                                                        |
+| --------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ignore`        | `(req: IncomingMessage) => boolean` | Predicate that excludes requests from locale routing. Return `true` to skip a request (e.g. API routes, health checks).                            |
+| `configOptions` | `GetConfigurationOptions`           | Intlayer configuration overrides forwarded to `getConfiguration()`. Use when you need the proxy to read a specific config file or override values. |
+
+### Example
+
+```ts
+intlayerProxy({
+  ignore: (req) => req.url?.startsWith("/api"),
+  configOptions: { configFile: "./config/intlayer.config.ts" },
+});
+```
+
+## createIntlayerProxyHandler
+
+`createIntlayerProxyHandler` creates a standalone, framework-agnostic Node.js `(req, res, next)` middleware that contains all the locale-routing logic. It is useful in environments where the Vite plugin API is unavailable (e.g. a plain Node.js server or a custom Nitro module).
+
+```ts
+import { createIntlayerProxyHandler } from "vite-intlayer";
+
+const handler = createIntlayerProxyHandler({
+  ignore: (req) => req.url?.startsWith("/api"),
+  configOptions: { configFile: "./config/intlayer.config.ts" },
+});
+
+// Express / Connect
+app.use(handler);
+```
+
+### Production SSR (TanStack Start / Nitro via h3)
+
+```ts
+// server/middleware/intlayerProxy.ts
+import { fromNodeMiddleware } from "h3";
+import { createIntlayerProxyHandler } from "vite-intlayer";
+
+export default fromNodeMiddleware(
+  createIntlayerProxyHandler({
+    ignore: (req) => req.url?.startsWith("/api"),
+  })
+);
+```
+
+## Routing behaviour
+
+The middleware mirrors the routing logic from `next-intlayer` middleware and supports all Intlayer routing modes.
+
+### Routing modes
+
+| Mode            | URL visible in browser   | Behaviour                                                                                               |
+| --------------- | ------------------------ | ------------------------------------------------------------------------------------------------------- |
+| `prefix`        | `/en/about`              | Default. Locale prefix in the URL. Default locale redirects to the un-prefixed URL unless `prefix-all`. |
+| `prefix-all`    | `/en/about`, `/fr/about` | All locales — including default — are always prefixed.                                                  |
+| `no-prefix`     | `/about`                 | No locale in the URL. Locale is stored in cookies only; URL rewrites happen internally.                 |
+| `search-params` | `/about?locale=en`       | Locale passed as a query parameter. Redirects to add/update the `locale` param when missing or stale.   |
+
+### Detection priority
+
+1. URL path prefix (e.g. `/fr/about` → `fr`).
+2. Cookie / localStorage value (`intlayer-locale`).
+3. `Accept-Language` header.
+4. `defaultLocale` from config.
+
+### Automatic bypass
+
+The middleware always passes these requests straight through without locale handling:
+
+- Requests matching the `ignore` predicate.
+- `/node_modules/**`
+- `/@**` – Vite internals (`@vite/`, `@fs/`, `@id/`, etc.).
+- `/_**` – server internals (`__vite_ping`, `__manifest`, etc.).
+- Requests whose path ends with a file extension (static assets). If a locale prefix is present on a static asset path (e.g. `/fr/logo.png`), it is stripped so the file can be served correctly.
+
+### Domain routing
+
+When `routing.domains` is configured in your Intlayer config, the middleware handles cross-domain locale routing:
+
+- A request for `/zh/about` on `intlayer.org` is redirected to `https://intlayer.zh/about` when `domains.zh = "intlayer.zh"`.
+- A request to `intlayer.zh/about` is rewritten internally to `/zh/about` so the `[locale]` route parameter is populated.
+
+### Redirect loop protection
+
+The middleware tracks redirect counts per `originalUrl → newUrl` pair within a 2-second sliding window. More than 10 redirects within that window returns a `500` response with a descriptive error instead of looping forever.
+
+## Nitro / production SSR (automatic injection, v9+)
+
+When `intlayerProxy` is used as a Vite plugin, it carries a `.nitro` property. The `nitro/vite` build plugin reads this property and pushes it into `nitroConfig.modules`, so `intlayerNitroHandler` is registered as a Nitro server middleware automatically — no manual configuration is needed for production SSR.
+
+The Nitro handler uses h3 v2's Web Fetch API event model (not `fromNodeMiddleware`) so it is compatible with all Nitro presets: Node, Bun, Deno, edge runtimes.
+
+## Deprecated aliases
+
+| Deprecated export          | Replacement     |
+| -------------------------- | --------------- |
+| `intlayerMiddleware`       | `intlayerProxy` |
+| `intLayerMiddlewarePlugin` | `intlayerProxy` |

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

@@ -1,45 +1,123 @@
 ---
 createdAt: 2026-01-21
-updatedAt: 2026-01-21
+updatedAt: 2026-06-25
 title: intlayerPrune Vite Plugin Documentation | vite-intlayer
-description: See how to use the intlayerPrune plugin for vite-intlayer package
+description: Vite plugin that tree-shakes unused dictionary fields from the production bundle to reduce bundle size.
 keywords:
   - intlayerPrune
   - vite
   - plugin
   - tree-shaking
-  - Intlayer
-  - intlayer
-  - Internationalization
-  - Documentation
+  - bundle size
+  - dictionary
+  - internationalization
+  - i18n
 slugs:
   - doc
   - packages
   - vite-intlayer
   - intlayerPrune
 history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "Expanded with field-level pruning, pruneContext, and edge-case details"
   - version: 8.0.0
     date: 2026-01-21
     changes: "Init doc"
 author: aymericzip
 ---
 
-# intlayerPrune Vite Plugin Documentation
+# intlayerPrune
 
-The `intlayerPrune` Vite plugin is used to tree-shake and prune unused dictionaries from your application bundle. This helps reduce the final bundle size by only including the necessary multilingual content.
+`intlayerPrune` is a Vite plugin that removes unused content fields from compiled dictionary JSON files during a production build. Instead of shipping every field from every dictionary, only the fields that are actually accessed in your source code are included in the bundle.
+
+> The plugin is already included and configured automatically when you use [`intlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/vite-intlayer/intlayer.md). You only need to register it manually if you are composing the plugin stack yourself.
 
 ## Usage
 
+### As part of `intlayer()` (recommended)
+
+Enable pruning through your Intlayer config and the main plugin handles everything:
+
+```ts
+// intlayer.config.ts
+import { defineConfig } from "intlayer";
+
+export default defineConfig({
+  build: {
+    optimize: true, // enables both prune and minify
+  },
+});
+```
+
 ```ts
 // vite.config.ts
 import { defineConfig } from "vite";
-import { intlayer, intlayerPrune } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
-  plugins: [intlayer(), intlayerPrune()],
+  plugins: [intlayer()],
 });
 ```
 
-## Description
+### Standalone
+
+If you are composing the plugin stack manually, `intlayerPrune` and `intlayerMinify` share a `PruneContext` object that must be created once and passed to both:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayerPrune, intlayerMinify } from "vite-intlayer";
+import { createPruneContext } from "@intlayer/babel";
+import { getConfiguration } from "@intlayer/config/node";
+
+const intlayerConfig = getConfiguration();
+const pruneContext = createPruneContext();
+
+export default defineConfig({
+  plugins: [
+    intlayerPrune(intlayerConfig, pruneContext),
+    intlayerMinify(intlayerConfig, pruneContext), // optional, reads from same context
+  ],
+});
+```
+
+## How it works
+
+### 1. Usage analysis (buildStart)
+
+During `buildStart`, the `intlayerOptimize` plugin (also part of `intlayer()`) scans every component source file listed in `build.filesList`. For each `useIntlayer('key')` or `getIntlayer('key')` call, it records exactly which fields are accessed, e.g.:
+
+```ts
+const { title, description } = useIntlayer("myDict");
+// records: myDict → { title, description }
+```
+
+This builds `pruneContext.fieldUsageMap` before any `transform` calls run.
+
+### 2. JSON pruning (transform, enforce: 'pre')
+
+When Vite processes a compiled dictionary JSON file, `intlayerPrune` intercepts it before Vite's built-in JSON → ESM conversion. It reads the field-usage map from `pruneContext` and removes any content field that is not in the recorded usage set.
+
+Two content shapes are supported:
+
+- **Static dictionaries** — `{ nodeType: "translation", translation: { en: {...}, fr: {...} } }`. Fields are pruned per-locale inside `translation`.
+- **Dynamic (per-locale) dictionaries** — flat `{ fieldA: ..., fieldB: ... }`. Fields are pruned at the top level.
+
+### 3. Edge cases
+
+If a dictionary's content structure cannot be recognised (e.g. an unusual nested shape), it is added to `pruneContext.dictionariesWithEdgeCases` and **left untouched**. A warning is logged. `intlayerMinify` also skips these dictionaries.
+
+### 4. Field-rename map
+
+When pruning succeeds, `intlayerPrune` also writes `pruneContext.dictionaryKeyToFieldRenameMap` — a mapping from original field names to short aliases. `intlayerMinify` reads this map to rename fields in the output JSON, and `intlayerOptimize`'s Babel rename pass updates property accesses in source files accordingly.
+
+## Activation conditions
+
+`intlayerPrune` is active **only** when all of the following are true:
+
+1. The Vite command is `build`.
+2. `build.optimize` is `true` (or `undefined`, which defaults to `true` for builds).
+3. `build.purge` is `true` in your Intlayer config.
 
-The plugin analyzes your source code to identify which dictionary keys are actually used. It then removes any unused content from the bundled dictionary files. This is particularly useful for large projects with many dictionaries where only a subset is used in specific pages or components.
+It is automatically **disabled** when `editor.enabled` is `true` because the editor needs the full dictionary content.

package/docs/en/plugins/sync-json.md

@@ -108,7 +108,6 @@ const config: IntlayerConfig = {
      * Will load, and write the output and translations back to the JSON files in the locales directory
      */
     syncJSON({
-      format: "i18next",
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
       priority: 0,
       format: "i18next",

package/docs/en/releases/v9.md

@@ -1,15 +1,14 @@
 ---
 createdAt: 2026-06-14
-updatedAt: 2026-06-23
+updatedAt: 2026-06-26
 title: New Intlayer v9 - What's new?
-description: Discover what's new in Intlayer v9. Introducing drop-in compatibility packages for popular i18n libraries and support for Collections, Variants, and Dynamic Records.
+description: Discover what's new in Intlayer v9. Introducing drop-in compatibility packages for popular i18n libraries and support for Collections and Variants.
 keywords:
   - Intlayer
   - Compatibility
   - Migration
   - Collections
   - Variants
-  - Dynamic Records
   - i18next
   - next-intl
   - vue-i18n
@@ -22,7 +21,7 @@ author: aymericzip
 
 # New Intlayer v9 - What's new?
 
-Welcome to Intlayer v9! This major release marks a huge milestone in simplifying the migration path to Intlayer with **Compat Adapter Packages** for major i18n libraries (`react-i18next`, `next-intl`, `vue-i18n`, etc.) and adds support for rich content structures: **Collections**, **Variants**, and **Dynamic Records**.
+Welcome to Intlayer v9! This major release marks a huge milestone in simplifying the migration path to Intlayer with **Compat Adapter Packages** for major i18n libraries (`react-i18next`, `next-intl`, `vue-i18n`, etc.) and adds support for rich content structures: **Collections** and **Variants**.
 
 ## Table of contents
 
@@ -41,8 +40,10 @@ By replacing imports, you get all the benefits of Intlayer (including compile-ti
 - `@intlayer/i18next`
 - `@intlayer/react-i18next`
 - `@intlayer/next-intl`
+- `@intlayer/react-intl`
 - `@intlayer/next-i18next`
 - `@intlayer/vue-i18n`
+- `@intlayer/lingui`
 
 For example, simply change:
 
@@ -100,7 +101,7 @@ All compat adapters now route translation resolution through a single, highly op
 
 ---
 
-## Feature Spec: Collections, Variants & Dynamic Records
+## Feature Spec: Collections & Variants
 
 Intlayer v9 expands beyond static key-value objects, allowing dictionaries to declare dynamic layout structures that are fully typed end-to-end.
 
@@ -136,6 +137,8 @@ const faq = useIntlayer("faq", { item: 1 }); // -> { question: string, answer: s
 
 Deliver A/B tests, seasonal headers, feature flags, or custom landing pages:
 
+#### String variants (e.g. A/B testing)
+
 ```ts fileName="hero.content.ts"
 import { t, type Dictionary } from "intlayer";
 
@@ -155,16 +158,14 @@ export default {
 const banner = useIntlayer("hero-banner", { variant: "black_friday" });
 ```
 
-### 3. Dynamic Records
-
-Define dictionaries whose entries are loaded dynamically at runtime via query IDs:
+#### Object variants (e.g. Dynamic Records)
 
 ```ts fileName="product.content.ts"
 import { t, type Dictionary } from "intlayer";
 
 export default {
   key: "product-copy",
-  meta: {
+  variant: {
     id: "prod_123",
     category: "books",
   },
@@ -217,7 +218,7 @@ export default defineConfig({
 });
 ```
 
-- **Compiler**: Activates automatically when `compiler.enabled` is set and a `compiler.output` path is configured. You no longer need to register `intlayerCompiler()` separately.
+- **Compiler**: Activates automatically when `compiler.enabled` is set to `true` and a `compiler.output` path is configured. You no longer need to register `intlayerCompiler()` separately.
 - **Proxy**: Activates automatically based on the new `routing.enableProxy` option (`true` by default). It wires the locale detection / redirect / rewrite middleware in development, preview, and production SSR. You no longer need to register `intlayerProxy()` separately.
 
 ### `routing.enableProxy` option
@@ -240,18 +241,64 @@ The standalone `intlayerCompiler()` and `intlayerProxy()` plugins remain exporte
 
 ---
 
+## Compiler disabled by default
+
+Starting with Intlayer v9, the **compiler is disabled by default** (`compiler.enabled` now defaults to `false`). To opt in to build-time extraction of your `.content.ts` files, set `compiler.enabled: true` in your configuration:
+
+```ts fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  compiler: {
+    enabled: true, // Default: false — required to enable the compiler since v9
+    output: ({ fileName }) => `./${fileName}.content.ts`,
+  },
+};
+
+export default config;
+```
+
+When the compiler is disabled, Intlayer skips the build-time extraction step and relies on your already-declared dictionaries. Enable it only when you want the bundler plugin (`@intlayer/swc`, `@intlayer/babel`, or the `intlayer()` Vite plugin) to extract content automatically.
+
+---
+
+## React Native: single-package imports
+
+In a React Native or Expo app, you no longer need to juggle both `react-intlayer` and `react-native-intlayer`. The `react-native-intlayer` package now **re-exports the full `react-intlayer` API** (hooks, utilities, and the `/format`, `/html`, and `/markdown` subpaths), and its `IntlayerProvider` automatically applies the React Native polyfills.
+
+Import everything from the single `react-native-intlayer` package:
+
+```tsx
+import {
+  IntlayerProvider,
+  useIntlayer,
+  useLocale,
+} from "react-native-intlayer";
+```
+
+```bash
+npm install intlayer react-native-intlayer
+```
+
+> Importing from `react-intlayer` keeps working, but `react-native-intlayer` is now the recommended single entry point for React Native — its provider ships the polyfills the web-oriented `react-intlayer` provider does not.
+
+---
+
 ## Migration notes from v8
 
 If you are upgrading from v8, note that the v9 does not include breaking changes. But here are the key changes:
 
+- **Compiler disabled by default**: `compiler.enabled` now defaults to `false`. If you rely on build-time extraction of your `.content.ts` files, set `compiler.enabled: true` in your `intlayer.config.ts`.
 - **Vite plugin**: The compiler and locale-routing proxy are now bundled into `intlayer()`. If you previously registered `intlayerCompiler()` or `intlayerProxy()` manually, you can remove them — they are deduplicated automatically, so keeping them is harmless. Use `routing.enableProxy: false` to opt out of the proxy.
 - **Locales & Dialects**: If using external i18n dependencies, add their respective compat adapter plugins in your configuration or bundler setup to automatically rewrite imports.
-- **Custom Selectors**: When calling `useIntlayer`, the second parameter is now reserved for an option object containing `{ locale, item, variant, id }`. If you previously passed a locale string directly, you can still do so, but using the options object is recommended for advanced selections.
+- **Custom Selectors**: When calling `useIntlayer`, the second parameter is now reserved for an option object containing `{ locale, item, variant }`. If you previously passed a locale string directly, you can still do so, but using the options object is recommended for advanced selections.
+- **React Native**: `react-native-intlayer` now re-exports the entire `react-intlayer` API. In a React Native app, import everything from `react-native-intlayer` and drop the direct `react-intlayer` dependency. Existing `react-intlayer` imports continue to work.
 
 ---
 
 ## Useful links
 
 - [Compat Adapter Packages Guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/index.md)
-- [Dynamic Dictionaries - Collections, Variants & Dynamic Records](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dynamic_dictionaries/index.md)
+- [Dynamic Dictionaries - Collections & Variants](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dynamic_dictionaries/index.md)
 - [Configuration Reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md)
+- [React Native & Expo Guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_react_native+expo.md)

package/docs/en-GB/compiler.md

@@ -81,12 +81,15 @@ Update your `vite.config.ts` to include the `intlayerCompiler` plugin:
 
 ```ts fileName="vite.config.ts"
 import { defineConfig } from "vite";
-import { intlayer, intlayerCompiler } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
   plugins: [
-    intlayer(),
-    intlayerCompiler(), // Adds the compiler plugin
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 });
 ```

package/docs/en-GB/custom_domains.md

@@ -172,10 +172,16 @@ The `intlayerProxy` Vite plugin applies the same logic during development:
 
 ```typescript fileName="vite.config.ts"
 import { defineConfig } from "vite";
-import { intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
-  plugins: [intlayerProxy()],
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
 });
 ```
 

package/docs/en-GB/custom_url_rewrites.md

@@ -342,10 +342,16 @@ For SolidJS, Vue, and Svelte, the `intlayerProxy` Vite plugin manages the rewrit
 
 ```typescript fileName="vite.config.ts"
 import { defineConfig } from "vite";
-import { intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
-  plugins: [intlayerProxy()],
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
 });
 ```
 

package/docs/en-GB/dynamic_dictionaries/index.md

@@ -1,15 +1,14 @@
 ---
 createdAt: 2026-06-12
-updatedAt: 2026-06-12
+updatedAt: 2026-06-26
 title: Dynamic Dictionaries
-description: Overview of Intlayer's three dynamic dictionary features — collections, variants, and dynamic records — for building flexible, runtime-driven i18n content.
+description: Overview of Intlayer's dynamic dictionary features — collections and variants — for building flexible, runtime-driven i18n content.
 keywords:
   - Dynamic Dictionaries
   - Collections
   - Variants
-  - Dynamic Records
   - Intlayer
-  - Internationalisation
+  - Internationalization
 slugs:
   - doc
   - concept
@@ -18,31 +17,38 @@ history:
   - version: 9.0.0
     date: 2026-06-12
     changes: "Release of the dynamic dictionaries feature"
+  - version: 9.1.0
+    date: 2026-06-26
+    changes: "Merged dynamic records into variants — `variant` now accepts a string or an object"
 author: aymericzip
 ---
 
 # Dynamic Dictionaries
 
-Intlayer supports three mechanisms for expressing content that goes beyond a single static dictionary per key. Each is declared through a **top-level metadata field** in the content file; no wrapper function is needed.
+Intlayer supports two mechanisms for expressing content that goes beyond a single static dictionary per key. Each is declared through a **top-level metadata field** in the content file; no wrapper function is needed.
 
-| Feature                                                                                                                     | Metadata field    | Selector in `useIntlayer` |
-| --------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------------------------- |
-| [Collections](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dynamic_dictionaries/collections.md)         | `item: N`         | `{ item: N }`             |
-| [Variants](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dynamic_dictionaries/variants.md)               | `variant: "name"` | `{ variant: "name" }`     |
-| [Dynamic Records](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dynamic_dictionaries/dynamic_content.md) | `meta: { id, … }` | `{ id, … }`               |
+| Feature                                                                                                          | Metadata field                          | Selector in `useIntlayer`                       |
+| ---------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ----------------------------------------------- |
+| [Collections](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dynamic_dictionaries/collections.md) | `item: N`                               | `{ item: N }`                                   |
+| [Variants](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dynamic_dictionaries/variants.md)       | `variant: "name"` _or_ `variant: { … }` | `{ variant: "name" }` _or_ `{ variant: { … } }` |
 
-All three compose with the locale argument and support selective / lazy loading via `importMode`.
+Both compose with the locale argument and support selective / lazy loading via `importMode`.
 
 ## When to use which
 
 - **Collections** — ordered list of items managed in separate files (FAQ entries, blog posts, products).
-- **Variants** — named content alternatives for A/B tests, seasonal banners, or feature flags.
-- **Dynamic records** — content fetched at runtime by an opaque ID (CMS records, user-specific copy).
+- **Variants** — named or structured content alternatives:
+  - a **string** variant for A/B tests, seasonal banners, or feature flags;
+  - an **object** variant for CMS records, user-specific copy, or any content addressed by a set of fields (the former "dynamic records").
+
+> Earlier versions exposed a separate `meta` field for record-keyed content. It has been merged into `variant`: pass an **object** to `variant` instead of using `meta`.
 
 ## Selector disambiguation
 
-When multiple selectors are present on a dictionary, the resolution order is:
+A key may declare both dimensions at once (e.g. a collection whose items each have a variant). They are resolved in the order:
 
 ```
-variant → meta → item
+variant → item
 ```
+
+So `{ variant: "promo" }` on a variant × item key returns every promo item as an array, and adding `{ item: 2 }` narrows it to a single entry.