@intlayer/docs 9.3.1 → 9.3.3

package/docs/en/eslint.md

@@ -0,0 +1,336 @@
+---
+createdAt: 2026-08-12
+updatedAt: 2026-08-13
+title: ESLint Plugin | Lint rules for Intlayer
+description: Catch hardcoded strings, dynamic calls the Intlayer compiler cannot optimize, and unused dictionary content, with eslint-plugin-intlayer. Works with ESLint and oxlint, across React, Vue, Svelte, Angular and Astro.
+keywords:
+  - Intlayer
+  - ESLint
+  - oxlint
+  - Linting
+  - i18n
+  - Internationalization
+  - no-raw-text
+  - Hardcoded strings
+  - Unused translations
+  - Dead content
+  - React
+  - Vue
+  - Svelte
+  - Angular
+slugs:
+  - doc
+  - eslint
+history:
+  - version: 9.3.1
+    date: 2026-08-12
+    changes: "Init history"
+author: aymericzip
+---
+
+# ESLint x OXLint Plugin
+
+`eslint-plugin-intlayer` catches the kinds of i18n mistake TypeScript cannot:
+
+1. **Hardcoded text** that never made it into a dictionary.
+2. **Dynamic calls** that type-check and run, but that the Intlayer compiler cannot optimize.
+3. **Dead content** — dictionaries and fields nothing in the project reads (opt-in).
+
+Unknown dictionary keys, unknown field paths and missing locales are already compile errors, so the plugin does not repeat them.
+
+## Installation
+
+```bash packageManager="npm"
+npm install --save-dev eslint-plugin-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add --save-dev eslint-plugin-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add --dev eslint-plugin-intlayer
+```
+
+Requires ESLint 9 or later (flat config). ESLint 10 is supported.
+
+## Usage
+
+The plugin runs in both ESLint and [oxlint](https://oxc.rs) — the same rules, the same options.
+
+<Tabs defaultTab="eslint">
+  <Tab label="ESLint" value="eslint">
+
+```javascript fileName="eslint.config.mjs"
+import intlayer from "eslint-plugin-intlayer";
+
+export default [...intlayer.configs.recommended];
+```
+
+Or spread a config and set the severities yourself:
+
+```javascript fileName="eslint.config.mjs"
+import intlayer from "eslint-plugin-intlayer";
+
+export default [
+  ...intlayer.configs.recommended,
+  {
+    rules: {
+      "intlayer/no-raw-text": "warn",
+      "intlayer/static-dictionary-key": "error",
+      "intlayer/no-dynamic-field-access": "error",
+      "intlayer/enforce-adapter-import": "warn",
+      "intlayer/no-unused-content": "warn",
+    },
+  },
+];
+```
+
+  </Tab>
+  <Tab label="oxlint" value="oxlint">
+
+```json fileName=".oxlintrc.json"
+{
+  "jsPlugins": ["eslint-plugin-intlayer"],
+  "rules": {
+    "intlayer/no-raw-text": "warn",
+    "intlayer/static-dictionary-key": "error",
+    "intlayer/no-dynamic-field-access": "error",
+    "intlayer/enforce-adapter-import": "warn"
+  }
+}
+```
+
+Two caveats: oxlint's JS plugin support is still alpha, and oxlint does not support custom parsers — so `.vue`, `.svelte`, `.astro` and Angular templates are not linted there. Run oxlint over your JS/TS/JSX files and keep ESLint for the rest.
+
+`no-unused-content` is left out above on purpose: it needs the working directory and the linted file path from the rule context, which the alpha JS plugin bridge does not guarantee. Run it under ESLint.
+
+  </Tab>
+</Tabs>
+
+### Configs
+
+| Config          | `no-raw-text`              | `static-dictionary-key` | `no-dynamic-field-access` | `enforce-adapter-import` | `no-unused-content` |
+| --------------- | -------------------------- | ----------------------- | ------------------------- | ------------------------ | ------------------- |
+| `recommended`   | warn                       | error                   | error                     | off                      | off                 |
+| `strict`        | error (+ non-JSX literals) | error                   | error                     | error                    | off                 |
+| `contract-only` | off                        | error                   | error                     | off                      | off                 |
+
+`recommended` keeps `no-raw-text` at `warn` on purpose: pointing it at an existing codebase surfaces every untranslated string at once, which should not break your build on day one.
+
+`enforce-adapter-import` is off by default — enable it explicitly if you want it.
+
+`no-unused-content` is off in every config, `strict` included. It is the one rule that reads your Intlayer configuration and walks your source files from disk, so turning it on should be a deliberate choice rather than something a preset does for you.
+
+## Rules
+
+### `no-raw-text`
+
+Reports user-facing text that is not declared in a dictionary. It uses the same detection as `intlayer extract`, so brand names, CSS classes and technical identifiers are ignored.
+
+```jsx
+// ✗ Reported
+<h1>Welcome to our documentation</h1>
+<input placeholder="Enter your email address" />
+
+// ✓ Fine
+const { title } = useIntlayer("home");
+<h1>{title}</h1>
+```
+
+Content declaration files (`*.content.ts`, …) are skipped.
+
+To fix a whole file at once, run `npx intlayer extract` and let the compiler move the strings into a dictionary for you.
+
+**Options**
+
+```javascript fileName="eslint.config.mjs"
+{
+  "intlayer/no-raw-text": [
+    "warn",
+    {
+      // Attributes whose value is user-facing text.
+      // Default: title, placeholder, alt, aria-label, label
+      attributes: ["title", "placeholder", "alt", "aria-label", "label"],
+
+      // Elements whose content is never user-facing text.
+      // Default: code, pre, script, style
+      ignoreElements: ["code", "pre", "script", "style"],
+
+      // Regular expressions for text to never report.
+      ignorePatterns: ["^Powered by"],
+
+      // Also report string literals outside markup. Default: false
+      includeStringLiterals: false,
+    },
+  ],
+}
+```
+
+### `static-dictionary-key`
+
+Requires the dictionary key to be a string literal.
+
+The compiler can only pre-load a dictionary when it can read the key directly at the call site. With a computed key it silently skips the optimization and bundles every dictionary instead.
+
+```typescript
+// ✗ Reported
+useIntlayer(dictionaryKey);
+useIntlayer(`home-${suffix}`);
+getTranslations({ namespace: page });
+
+// ✗ A variable is still not a literal
+const key = "home";
+useIntlayer(key);
+
+// ✓ Fine
+useIntlayer("home");
+getTranslations({ namespace: "home" });
+```
+
+This applies to `useIntlayer`, `getIntlayer` and every compat adapter (`useTranslation`, `useTranslations`, `formatMessage`, `<FormattedMessage id>`, `<Trans i18nKey>`, …).
+
+### `no-dynamic-field-access`
+
+Requires the field you read from a dictionary to be statically known.
+
+The compiler removes fields it does not see used. A computed access is invisible to it, so the read can return `undefined` at runtime.
+
+```typescript
+// ✗ Reported
+const content = useIntlayer("home");
+content[fieldName];
+
+const t = useTranslations("home");
+t(messageKey);
+
+// ✓ Fine
+content.title;
+content["title"];
+content.items[0];
+t("hero.title");
+```
+
+### `enforce-adapter-import`
+
+Prefers the `@intlayer/*` compat adapter over the original package. The original only resolves to Intlayer when the bundler alias is configured; the adapter always does. Autofixable with `--fix`.
+
+```typescript
+// ✗ Reported
+import { useTranslation } from "react-i18next";
+import { getTranslations } from "next-intl/server";
+
+// ✓ Fine
+import { useTranslation } from "@intlayer/react-i18next";
+import { getTranslations } from "@intlayer/next-intl/server";
+```
+
+### `no-unused-content`
+
+**Off by default.** Reports content nothing in your project reads, plus dictionary keys declared in more than one place.
+
+```typescript fileName="src/home.content.ts"
+export default {
+  key: "home", // ✗ Reported when no caller anywhere asks for "home"
+  content: {
+    title: t({ en: "Title" }),
+
+    // ✗ Reported when nothing reads `hero`
+    hero: {
+      subtitle: t({ en: "Subtitle" }),
+    },
+  },
+};
+```
+
+Unlike the other rules, this one cannot answer from the file in front of it — a field is unused only relative to the whole project. On the first content declaration of a lint run it loads your Intlayer configuration, globs the source files that configuration declares (`build.traversePattern`, `compiler.transformPattern`) and runs the same usage analyser that powers `@intlayer/lsp` and the "unused" strikethrough in the VS Code extension. The result is cached for `cacheTtl` milliseconds, so the scan happens once per run rather than once per file.
+
+**Options**
+
+```javascript fileName="eslint.config.mjs"
+{
+  "intlayer/no-unused-content": [
+    "warn",
+    {
+      // Report dictionary keys nothing references. Default: true
+      reportUnusedDictionaries: true,
+
+      // Report content fields nothing reads. Default: true
+      reportUnusedFields: true,
+
+      // Report keys declared in more than one place. Default: true
+      reportDuplicateKeys: true,
+
+      // Regular expressions for field paths to never report.
+      ignoreFields: ["^meta"],
+
+      // Project root the scan starts from. Default: ESLint's working directory
+      baseDir: process.cwd(),
+
+      // How long one project scan is reused, in ms. Default: 30000
+      cacheTtl: 30000,
+    },
+  ],
+}
+```
+
+Lower `cacheTtl` when you lint from a long-lived editor server and want your edits reflected sooner; set `baseDir` when a single lint run spans several Intlayer projects in a monorepo.
+
+> **It errs towards silence.** A false positive here deletes a translation, so nothing is reported when the dictionary is consumed in a way the analysis cannot follow: the content object passed on as a whole, a translator function bound from it (`const t = useTranslations("home")`), a declaration reached through a direct import (`useDictionary(myDictionary)`), a `nest()` from another dictionary, or a field list made non-exhaustive by a spread. Single-file components (`.vue`, `.svelte`, `.astro`) count as using every field of the dictionaries they mention, because their script blocks are not parsed here.
+
+`reportDuplicateKeys` reads the unmerged dictionaries the build writes under `.intlayer/`, so it stays quiet until the project has been built at least once. Two declarations sharing a key are merged, which is a legitimate pattern — the report exists because a field defined on both sides silently keeps only one of the two values.
+
+The analyser is loaded from `@intlayer/lsp`, which ships as ESM. The rule therefore needs a Node version that can `require()` an ES module — Node 20.19+ or 22.12+. On anything older it reports nothing rather than failing the lint run.
+
+## Frameworks
+
+Every rule works across all Intlayer integrations, including inside Vue, Svelte and Angular templates. You only need to tell ESLint which parser reads each file type.
+
+| Framework                 | Files             | Parser                            |
+| ------------------------- | ----------------- | --------------------------------- |
+| React, Preact, Solid, Lit | `.jsx` `.tsx`     | `typescript-eslint`               |
+| Next.js                   | `.jsx` `.tsx`     | `typescript-eslint`               |
+| Vue, Nuxt                 | `.vue`            | `vue-eslint-parser`               |
+| Svelte, SvelteKit         | `.svelte`         | `svelte-eslint-parser`            |
+| Angular                   | `.ts`             | `typescript-eslint`               |
+| Angular templates         | `.component.html` | `@angular-eslint/template-parser` |
+| Astro                     | `.astro`          | `astro-eslint-parser`             |
+
+```javascript fileName="eslint.config.mjs"
+import intlayer from "eslint-plugin-intlayer";
+import tseslint from "typescript-eslint";
+import vueParser from "vue-eslint-parser";
+import svelteParser from "svelte-eslint-parser";
+import angularTemplateParser from "@angular-eslint/template-parser";
+
+export default [
+  ...intlayer.configs.recommended,
+
+  {
+    files: ["**/*.{ts,tsx,jsx}"],
+    languageOptions: { parser: tseslint.parser },
+  },
+  {
+    files: ["**/*.vue"],
+    languageOptions: {
+      parser: vueParser,
+      parserOptions: { parser: tseslint.parser },
+    },
+  },
+  {
+    files: ["**/*.svelte"],
+    languageOptions: {
+      parser: svelteParser,
+      parserOptions: { parser: tseslint.parser },
+    },
+  },
+  {
+    files: ["**/*.component.html"],
+    languageOptions: { parser: angularTemplateParser },
+  },
+];
+```
+
+Install only the parsers your project needs.
+
+> **Known limitation.** In Vue and Angular templates, an expression such as `{{ content[key] }}` is not checked by `no-dynamic-field-access`. Dynamic reads written in the script block are caught normally.

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

@@ -19,6 +19,9 @@ slugs:
   - intlayer
   - getLocalizedPath
 history:
+  - version: 8.0.0
+    date: 2026-08-19
+    changes: "Apply the locale prefix, and narrow the return type from the declared rewrite rules"
   - version: 8.0.0
     date: 2026-01-22
     changes: "Implement custom URL rewrites"
@@ -29,13 +32,17 @@ author: aymericzip
 
 ## Description
 
-The `getLocalizedPath` function resolves a canonical path (internal application path) into its localized equivalent based on the provided locale and rewrite rules. It is particularly useful for generating SEO-friendly URLs that vary by language.
+The `getLocalizedPath` function localizes a canonical path (internal application path): it resolves the custom rewrite rules, then applies the locale prefix of your routing mode. It is particularly useful for generating SEO-friendly URLs that vary by language.
+
+It is the relative counterpart of [`getLocalizedUrl`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getLocalizedUrl.md) — for a relative input both return the same value. Unlike `getLocalizedUrl`, it never returns an absolute URL: the `domains` configuration is ignored, so a locale served from its own domain still yields a path. An absolute input is accepted, but its origin is dropped — only its path, query string and hash are kept.
 
 **Key Features:**
 
 - Supports dynamic route parameters using the `[param]` syntax.
 - Resolves paths according to custom rewrite rules defined in your configuration.
+- Applies the locale prefix of the configured routing mode (`prefix-no-default`, `prefix-all`, …).
 - Automatically handles fallback to the canonical path if no rewrite rule is found for the specified locale.
+- Narrows its return type: a literal path resolves to the localized string literal at compile time.
 
 ---
 
@@ -43,9 +50,14 @@ The `getLocalizedPath` function resolves a canonical path (internal application
 
 ```typescript
 getLocalizedPath(
-  canonicalPath: string,         // Required
-  locale: Locales,               // Required
-  rewriteRules?: RoutingConfig['rewrite'] // Optional
+  canonicalPath: string,     // Required
+  locale?: Locales,          // Optional
+  options?: {                // Optional
+    locales?: Locales[];
+    defaultLocale?: Locales;
+    mode?: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params';
+    rewrite?: RoutingConfig['rewrite'];
+  }
 ): string
 ```
 
@@ -60,17 +72,21 @@ getLocalizedPath(
   - **Type**: `string`
   - **Required**: Yes
 
-- `locale: Locales`
+### Optional Parameters
+
+- `locale?: Locales`
   - **Description**: The target locale for which the path should be localized.
   - **Type**: `Locales`
-  - **Required**: Yes
+  - **Default**: The default locale of your project's configuration.
 
-### Optional Parameters
+- `options?: object`
+  - **Description**: Routing overrides. Every entry defaults to your project's configuration.
+  - **Type**: `object`
 
-- `rewriteRules?: RoutingConfig['rewrite']`
-  - **Description**: An object defining custom rewrite rules. If not provided, it defaults to the `routing.rewrite` property from your project's configuration.
-  - **Type**: `RoutingConfig['rewrite']`
-  - **Default**: `configuration.routing.rewrite`
+  - `options.locales?: Locales[]` — supported locales. **Default**: `configuration.internationalization.locales`
+  - `options.defaultLocale?: Locales` — the default locale. **Default**: `configuration.internationalization.defaultLocale`
+  - `options.mode?: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'` — how the locale appears in the path. **Default**: `configuration.routing.mode`
+  - `options.rewrite?: RoutingConfig['rewrite']` — custom rewrite rules. **Default**: `configuration.routing.rewrite`
 
 ---
 
@@ -79,6 +95,28 @@ getLocalizedPath(
 - **Type**: `string`
 - **Description**: The localized path for the specified locale.
 
+The type is narrowed from the rewrite rules declared in your configuration, so the editor shows the resolved path rather than a bare `string`:
+
+```typescript codeFormat="typescript"
+// Configuration: mode 'prefix-no-default', defaultLocale 'en',
+//                { '/about': { fr: '/a-propos' }, '/product/[id]': { fr: '/produit/[id]' } }
+const about = getLocalizedPath("/about", Locales.FRENCH);
+//    ^? '/fr/a-propos'
+const product = getLocalizedPath("/product/123", Locales.FRENCH);
+//    ^? '/fr/produit/123'
+const contact = getLocalizedPath("/contact", Locales.FRENCH);
+//    ^? '/fr/contact'  (no rewrite rule matches, only the prefix is applied)
+const home = getLocalizedPath("/", Locales.FRENCH);
+//    ^? '/fr'
+```
+
+The same narrowing flows into [`getLocalizedUrl`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getLocalizedUrl.md), which applies the rewrite rules before prefixing the locale.
+
+Two cases stay widened to `string`, because they cannot be resolved at compile time:
+
+- a path that is not a string literal (e.g. one built from a variable);
+- a path matched by a rule using a multi-segment or optional parameter (`[...slug]`, `[[...slug]]`, `:param?`).
+
 ---
 
 ## Example Usage
@@ -90,12 +128,13 @@ If you have configured custom rewrites in your `intlayer.config.ts`:
 ```typescript codeFormat="typescript"
 import { getLocalizedPath, Locales } from "intlayer";
 
-// Configuration: { '/about': { en: '/about', fr: '/a-propos' } }
+// Configuration: mode 'prefix-no-default', defaultLocale 'en',
+//                { '/about': { en: '/about', fr: '/a-propos' } }
 getLocalizedPath("/about", Locales.FRENCH);
-// Output: "/a-propos"
+// Output: "/fr/a-propos"
 
 getLocalizedPath("/about", Locales.ENGLISH);
-// Output: "/about"
+// Output: "/about" (default locale, no prefix)
 ```
 
 ### Usage with Dynamic Routes
@@ -105,7 +144,7 @@ import { getLocalizedPath, Locales } from "intlayer";
 
 // Configuration: { '/product/[id]': { en: '/product/[id]', fr: '/produit/[id]' } }
 getLocalizedPath("/product/123", Locales.FRENCH);
-// Output: "/produit/123"
+// Output: "/fr/produit/123"
 ```
 
 ### Manual Rewrite Rules
@@ -122,13 +161,25 @@ const manualRules = {
   },
 };
 
-getLocalizedPath("/contact", Locales.FRENCH, manualRules);
-// Output: "/contactez-nous"
+getLocalizedPath("/contact", Locales.FRENCH, { rewrite: manualRules });
+// Output: "/fr/contactez-nous"
+```
+
+### Omitting the Locale
+
+When no locale is given, the path is localized for the configured default locale:
+
+```typescript codeFormat="typescript"
+import { getLocalizedPath } from "intlayer";
+
+// Configuration: defaultLocale = Locales.ENGLISH, { '/about': { en: '/about', fr: '/a-propos' } }
+getLocalizedPath("/about");
+// Output: "/about"
 ```
 
 ---
 
 ## Related Functions
 
-- [`getCanonicalPath`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getCanonicalPath.md): Resolves a localized path back to its internal canonical path.
-- [`getLocalizedUrl`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getLocalizedUrl.md): Generates a fully localized URL (including protocol, host, and locale prefix).
+- [`getCanonicalPath`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getCanonicalPath.md): Resolves a localized path back to its internal canonical path. Note that it undoes the rewrite rules only — strip the locale prefix with [`getPathWithoutLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getPathWithoutLocale.md) first.
+- [`getLocalizedUrl`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getLocalizedUrl.md): Same localization, but able to return an absolute URL (protocol, host, domain routing).

package/docs/en-GB/configuration.md

@@ -479,6 +479,28 @@ const config: IntlayerConfig = {
      */
     purge: true,
 
+    /**
+     * Group the per-locale dictionary chunks by the code-split boundary that uses
+     * them, so a lazily loaded page fetches its content in one request.
+     * Default: true
+     *
+     * Note:
+     * - Only applies to dictionaries using `importMode: 'dynamic'`.
+     */
+    chunkGrouping: true,
+
+    /**
+     * Load a dictionary together with the chunk that uses it, instead of fetching
+     * it once that chunk renders. Readers render synchronously instead of
+     * suspending, so navigating no longer flashes a loading state.
+     * Default: true
+     *
+     * Note:
+     * - Only the resolved locale is awaited, so a page still downloads only the
+     *   language it renders.
+     */
+    dictionariesPreload: true,
+
     /**
      * Output format for generated dictionary files.
      * Default: ['cjs', 'esm']
@@ -1060,15 +1082,17 @@ Build options apply to the `@intlayer/babel` and `@intlayer/swc` plugins.
 
 > When optimized, Intlayer will replace dictionary calls to optimize chunking, so the final bundle only imports dictionaries that are actually used.
 
-| Field             | Description                                                               | Type                             | Default                                                                                                                                                                           | Example                                                                       | Note                                                                                                                                                                                                                                                                                                                                                                      |
-| ----------------- | ------------------------------------------------------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mode`            | Controls the mode of the build.                                           | `'auto'` &#124; <br/> `'manual'` | `'auto'`                                                                                                                                                                          | `'manual'`                                                                    | • `'auto'`: build enabled automatically when the application is built.<br/>• `'manual'`: only runs when the build command is executed.<br/>• Can be used to disable dictionary builds (e.g. to avoid running in Node.js environments).                                                                                                                                    |
-| `optimize`        | Controls whether the build should be optimized.                           | `boolean`                        | `undefined`                                                                                                                                                                       | `process.env.NODE_ENV === 'production'`                                       | • If unset, optimization is triggered on framework build (Vite/Next.js).<br/>• `true` forces optimization including dev mode.<br/>• `false` disables it.<br/>• When enabled, replaces dictionary calls to optimize chunking - only used dictionaries are imported.<br/>• Relies on `@intlayer/babel` and `@intlayer/swc` plugins.<br/>• Keys must be declared statically. |
-| `minify`          | Defines if the dictionaries should be minified to reduce the bundle size. | `boolean`                        | `false`                                                                                                                                                                           |                                                                               | • Defines if the bundle should be minified.<br/>• Default: `false` in production.<br/>• This option will be ignored if `optimize` is disabled.<br/>• This option will be ignored if `editor.enabled` is true.                                                                                                                                                             |
-| `prune`           | Defines if the unused keys in dictionaries should be purged.              | `boolean`                        | `true`                                                                                                                                                                            |                                                                               | • Defines if the bundle should be pruned.<br/>• Default: `true` in production.<br/>• This option will be ignored if `optimize` is disabled.                                                                                                                                                                                                                               |
-| `checkTypes`      | Indicates if the build should check TypeScript types and log errors.      | `boolean`                        | `false`                                                                                                                                                                           |                                                                               | Can slow down the build.                                                                                                                                                                                                                                                                                                                                                  |
-| `outputFormat`    | Controls the output format of the dictionaries.                           | `('esm' &#124; 'cjs')[]`         | `['esm', 'cjs']`                                                                                                                                                                  | `['cjs']`                                                                     |                                                                                                                                                                                                                                                                                                                                                                           |
-| `traversePattern` | Patterns defining which files to traverse during optimization.            | `string[]`                       | `['**/*.{tsx,ts,js,mjs,cjs,jsx,vue,svelte,svte}', '!**/node_modules/**', '!**/dist/**', '!**/.intlayer/**', '!**/*.config.*', '!**/*.test.*', '!**/*.spec.*', '!**/*.stories.*']` | `['src/**/*.{ts,tsx}', '../ui-library/**/*.{ts,tsx}', '!**/node_modules/**']` | • Limit optimization to relevant files to improve build performance.<br/>• Ignored if `optimize` is disabled.<br/>• Uses glob pattern.                                                                                                                                                                                                                                    |
+| Field                 | Description                                                                                                              | Type                             | Default                                                                                                                                                                           | Example                                                                       | Note                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mode`                | Controls the mode of the build.                                                                                          | `'auto'` &#124; <br/> `'manual'` | `'auto'`                                                                                                                                                                          | `'manual'`                                                                    | • `'auto'`: build enabled automatically when the application is built.<br/>• `'manual'`: only runs when the build command is executed.<br/>• Can be used to disable dictionary builds (e.g. to avoid running in Node.js environments).                                                                                                                                                                                                                                                                                           |
+| `optimize`            | Controls whether the build should be optimized.                                                                          | `boolean`                        | `undefined`                                                                                                                                                                       | `process.env.NODE_ENV === 'production'`                                       | • If unset, optimization is triggered on framework build (Vite/Next.js).<br/>• `true` forces optimization including dev mode.<br/>• `false` disables it.<br/>• When enabled, replaces dictionary calls to optimize chunking - only used dictionaries are imported.<br/>• Relies on `@intlayer/babel` and `@intlayer/swc` plugins.<br/>• Keys must be declared statically.                                                                                                                                                        |
+| `minify`              | Defines if the dictionaries should be minified to reduce the bundle size.                                                | `boolean`                        | `false`                                                                                                                                                                           |                                                                               | • Defines if the bundle should be minified.<br/>• Default: `false` in production.<br/>• This option will be ignored if `optimize` is disabled.<br/>• This option will be ignored if `editor.enabled` is true.                                                                                                                                                                                                                                                                                                                    |
+| `prune`               | Defines if the unused keys in dictionaries should be purged.                                                             | `boolean`                        | `true`                                                                                                                                                                            |                                                                               | • Defines if the bundle should be pruned.<br/>• Default: `true` in production.<br/>• This option will be ignored if `optimize` is disabled.                                                                                                                                                                                                                                                                                                                                                                                      |
+| `checkTypes`          | Indicates if the build should check TypeScript types and log errors.                                                     | `boolean`                        | `false`                                                                                                                                                                           |                                                                               | Can slow down the build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `chunkGrouping`       | Whether to group the per-locale dictionary chunks by the code-split boundary that uses them.                             | `boolean`                        | `true`                                                                                                                                                                            |                                                                               | • Without grouping, a page assembled from many components issues one request per dictionary.<br/>• Dictionaries reached from several boundaries move to a shared chunk, so no page ships another page's content.<br/>• Only applies to dictionaries using `importMode: 'dynamic'`.<br/>• Only applies to the client build, and only when bundling (not in dev).                                                                                                                                                                  |
+| `dictionariesPreload` | Whether a dictionary should load together with the chunk that uses it, instead of being fetched once that chunk renders. | `boolean`                        | `true`                                                                                                                                                                            |                                                                               | • The generated entry point awaits the browsing locale at the top level, so a lazily loaded route is not considered loaded until its content is there.<br/>• Readers render synchronously instead of suspending, so navigating no longer flashes a loading state.<br/>• Only the resolved locale is awaited, so a page still downloads only the language it renders.<br/>• Only applies to dictionaries using `importMode: 'dynamic'`, on the client build.<br/>• Requires a bundler supporting top-level await (Vite, esbuild). |
+| `outputFormat`        | Controls the output format of the dictionaries.                                                                          | `('esm' &#124; 'cjs')[]`         | `['esm', 'cjs']`                                                                                                                                                                  | `['cjs']`                                                                     |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `traversePattern`     | Patterns defining which files to traverse during optimization.                                                           | `string[]`                       | `['**/*.{tsx,ts,js,mjs,cjs,jsx,vue,svelte,svte}', '!**/node_modules/**', '!**/dist/**', '!**/.intlayer/**', '!**/*.config.*', '!**/*.test.*', '!**/*.spec.*', '!**/*.stories.*']` | `['src/**/*.{ts,tsx}', '../ui-library/**/*.{ts,tsx}', '!**/node_modules/**']` | • Limit optimization to relevant files to improve build performance.<br/>• Ignored if `optimize` is disabled.<br/>• Uses glob pattern.                                                                                                                                                                                                                                                                                                                                                                                           |
 
 ---
 

package/docs/en-GB/dictionary/content_file.md

@@ -532,28 +532,6 @@ Used in conjunction with Variants, this field defines named content alternatives
 
 > See [Variants](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dynamic_dictionaries/variants.md) for more information.
 
-#### `meta` (`Record<string, string | number | boolean>`)
-
-Used in conjunction with Dynamic Records, this field allows declaring CMS-managed records or arbitrary data fetched at runtime by an opaque ID. The dictionary identity is defined by the arbitrary set of key-value pairs declared in this `meta` field.
-
-**Example:**
-
-```typescript
-{
-  key: "product-copy",
-  meta: {
-    id: "prod_abc",
-    userId: "user_123"
-  },
-  content: {
-    name: "Widget Pro",
-    description: "The best widget."
-  }
-}
-```
-
-> See [Dynamic Records](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dynamic_dictionaries/dynamic_content.md) for more information.
-
 ### CMS Properties
 
 ##### `version` (string)

package/docs/en-GB/dictionary/function_fetching.md

@@ -85,6 +85,29 @@ No way to fetch content from a JSON file, use a .ts or .js file instead
 
 In this case, the `fakeFetch` function mimics a delay to simulate server response time. Intlayer executes the asynchronous function and uses the result as the content for the `text` key.
 
+## Fetching Remote Content
+
+You can also assign a promise directly to a content field. Intlayer awaits it while building the dictionaries and inlines the resolved value:
+
+```typescript fileName="**/*.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+import type { Dictionary } from "intlayer";
+
+const remoteContent = {
+  key: "remote_content",
+  content: {
+    externalContent: fetch("https://example.com").then((res) => res.json()),
+  },
+} satisfies Dictionary;
+
+export default remoteContent;
+```
+
+```plaintext fileName="**/*.content.json" contentDeclarationFormat="json"
+No way to fetch content from a JSON file, use a .ts or .js file instead
+```
+
+> The request runs at build time, so the fetched data is a snapshot embedded in the dictionary. Rebuild your dictionaries to refresh it.
+
 ## Using Function-Based Content in React Components
 
 To use function-based content in a React component, you need to import `useIntlayer` from `react-intlayer` and call it with the content ID to retrieve the content. Here's an example: