@intlayer/docs 8.12.2 → 8.12.4-canary.0

package/docs/en-GB/bundle_optimization.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2025-11-25
-updatedAt: 2026-04-08
-title: Optimising i18n Bundle Size & Performance
-description: Reduce application bundle size by optimising internationalisation (i18n) content. Learn how to leverage tree shaking and lazy loading for dictionaries with Intlayer.
+updatedAt: 2026-06-07
+title: i18n Bundle Size & Performance Optimisation
+description: Reduce your application bundle size by optimising internationalisation (i18n) content. Learn how to leverage tree shaking and lazy loading for dictionaries with Intlayer.
 keywords:
   - Bundle Optimisation
   - Content Automation
@@ -16,33 +16,36 @@ slugs:
   - concept
   - bundle-optimization
 history:
+  - version: 8.12.0
+    date: 2026-06-07
+    changes: "Added `intlayerPurgeBabelPlugin` and `intlayerMinifyBabelPlugin` for Babel/Webpack; clarified the plugin pipeline"
   - version: 8.7.0
     date: 2026-04-08
-    changes: "Add `minify` and `purge` options to the build configuration"
+    changes: "Added `minify` and `purge` options to build configuration"
 ---
 
-# Optimising i18n Bundle Size & Performance
+# i18n Bundle Size & Performance Optimisation
 
-One of the most common challenges with traditional i18n solutions relying on JSON files is managing content size. If developers do not manually separate content into namespaces, users often end up downloading translations for every page and potentially every language just to view a single page.
+One of the most common challenges with traditional i18n solutions relying on JSON files is managing content size. If developers do not manually separate content into namespaces, users often end up downloading the translations for every page and potentially every language just to view a single page.
 
-For example, an application with 10 pages translated into 10 languages might result in a user downloading the content of 100 pages, even though they only need **one** (the current page in the current language). This leads to wasted bandwidth and slower load times.
+For example, an application with 10 pages translated into 10 languages could result in a user downloading 100 pages' worth of content, even though they only need **one** (the current page in the current language). This leads to wasted bandwidth and slower load times.
 
-**Intlayer solves this problem through build-time optimisation.** It analyses your code to detect which dictionaries are actually used per component and reinjects only the necessary content into your bundle.
+**Intlayer solves this problem through build-time optimisation.** It analyses your code to detect exactly which dictionaries are actually used per component and re-injects only the necessary content into your bundle.
 
 ## Table of Contents
 
 <TOC />
 
-## Scan your bundle
+## Analyse your bundle
 
-Analysing your bundle is the first step in identifying "heavy" JSON files and code-splitting opportunities. These tools generate a visual treemap of your application's compiled code, allowing you to see exactly which libraries are consuming the most space.
+Analysing your bundle is the first step to identifying "heavy" JSON files and opportunities for code-splitting. These tools generate a visual treemap of your application's compiled code, allowing you to see exactly which libraries are taking up the most space.
 
 <Tabs>
  <Tab value="vite">
 
 ### Vite / Rollup
 
-Vite uses Rollup under the hood. The `rollup-plugin-visualizer` generates an interactive HTML file showing the size of every module in your graph.
+Vite uses Rollup under the hood. The `rollup-plugin-visualizer` generates an interactive HTML file showing the size of each module in your graph.
 
 ```bash
 npm install -D rollup-plugin-visualizer
@@ -69,7 +72,7 @@ export default defineConfig({
 
 ### Next.js (Turbopack)
 
-For projects using the App Router and Turbopack, Next.js provides a built-in experimental analyser that requires no extra dependencies.
+For projects using the App Router and Turbopack, Next.js provides a built-in, experimental analyser that requires no extra dependencies.
 
 ```bash packageManager='npm'
 npx next experimental-analyze
@@ -131,7 +134,7 @@ ANALYZE=true npm run build
 
 ### Standard Webpack
 
-For Create React App (ejected), Angular, or custom Webpack setups, use the industry-standard `webpack-bundle-analyzer`.
+For Create React App (ejected), Angular, or custom Webpack setups, use the industry standard `webpack-bundle-analyzer`.
 
 ```bash packageManager='npm'
 npm install -D webpack-bundle-analyzer
@@ -149,7 +152,7 @@ pnpm add -D webpack-bundle-analyzer
 bun add -d webpack-bundle-analyzer
 ```
 
-```typescript fileName="webpack.config.ts
+```typescript fileName="webpack.config.ts"
 import { BundleAnalyzerPlugin } from "webpack-bundle-analyzer";
 
 export default {
@@ -166,19 +169,56 @@ export default {
  </Tab>
 </Tabs>
 
-## How It Works
+## How it works
 
-Intlayer uses a **per-component approach**. Unlike global JSON files, your content is defined alongside or within your components. During the build process, Intlayer:
+Intlayer uses a **per-component approach**. Unlike global JSON files, your content is defined alongside or within your components. During the build process, Intlayer will:
 
-1.  **Analyses** your code to find `useIntlayer` calls.
-2.  **Builds** the corresponding dictionary content.
-3.  **Replaces** the `useIntlayer` call with optimised code based on your configuration.
+1. **Analyse** your code to find `useIntlayer` calls.
+2. **Build** the corresponding dictionary content.
+3. **Replace** the `useIntlayer` call with optimised code based on your configuration.
 
 This ensures that:
 
 - If a component is not imported, its content is not included in the bundle (Dead Code Elimination).
 - If a component is lazy-loaded, its content is also lazy-loaded.
 
+## Plugin Reference
+
+Intlayer's build optimisation is split into several discrete plugins, each with a single responsibility. Understanding what each one does prevents confusion when configuring them.
+
+### Babel plugins (`@intlayer/babel`)
+
+These are used directly in `babel.config.js` for Webpack-based setups (Next.js with Babel, CRA, custom Webpack, etc).
+
+| Plugin                        | What it does                                                                                                        |
+| :---------------------------- | :------------------------------------------------------------------------------------------------------------------ |
+| `intlayerExtractBabelPlugin`  | Scans `.content.ts` files and writes compiled dictionaries to `.intlayer/`                                          |
+| `intlayerOptimizeBabelPlugin` | Rewrites `useIntlayer('key')` → `useDictionary(hash)` and injects the matching dictionary `import`                  |
+| `intlayerPurgeBabelPlugin`    | Scans all source files, removes **unused content fields** from the compiled `.intlayer/**/*.json` dictionary files  |
+| `intlayerMinifyBabelPlugin`   | **Renames content field keys** to short alphabetical aliases (`title` → `a`) in both JSON files and the source code |
+
+> **Plugin order matters.** In your `babel.config.js` the purge and minify plugins must appear **before** the optimize plugin. The optimize pass replaces `useIntlayer('key')` with an opaque `useDictionary(hash)` call, wiping out the dictionary key information the purge and minify passes need to identify which fields are used.
+
+Each Babel plugin has a corresponding options helper that reads your `intlayer.config.ts` once at config load time and returns pre-resolved values:
+
+| Options helper               | Used with                     |
+| :--------------------------- | :---------------------------- |
+| `getExtractPluginOptions()`  | `intlayerExtractBabelPlugin`  |
+| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin` |
+| `getPurgePluginOptions()`    | `intlayerPurgeBabelPlugin`    |
+| `getMinifyPluginOptions()`   | `intlayerMinifyBabelPlugin`   |
+
+### Vite plugins (`vite-intlayer`)
+
+Vite users **never configure these directly**. They are wired up automatically when you call `withIntlayer()` in `vite.config.ts`. The `build.purge` and `build.minify` flags in `intlayer.config.ts` toggle the corresponding behaviour without any extra plugin registration.
+
+| Internal Vite plugin | Equivalent behaviour                                                                   |
+| :------------------- | :------------------------------------------------------------------------------------- |
+| Usage analyzer       | Same as `intlayerPurgeBabelPlugin` analyse pass                                        |
+| Dictionary prune     | Same as `intlayerPurgeBabelPlugin` JSON write pass                                     |
+| Dictionary minify    | Same as `intlayerMinifyBabelPlugin` JSON write pass                                    |
+| Babel transform      | Same as `intlayerMinifyBabelPlugin` source code rename + `intlayerOptimizeBabelPlugin` |
+
 ## Setup by Platform
 
 <Tabs>
@@ -186,9 +226,9 @@ This ensures that:
 
 ### Next.js
 
-Next.js requires the `@intlayer/swc` plugin to handle the transformation, as Next.js uses SWC for builds.
+Next.js requires the `@intlayer/swc` plugin for the optimise (import rewrite) pass, because Next.js uses SWC for builds.
 
-> This plugin is not installed by default because SWC plugins are still experimental for Next.js. It may change in the future.
+> This plugin is not installed by default as SWC plugins are still experimental for Next.js. This may change in the future.
 
 ```bash packageManager="npm"
 npm install -D @intlayer/swc
@@ -206,21 +246,63 @@ pnpm add -D @intlayer/swc
 bun add -d @intlayer/swc
 ```
 
-Once Installed. Intlayer will automatically detect and use the plugin.
+Once installed, Intlayer will automatically detect and use the plugin.
+
+For the **purge and minify** passes (field removal and field rename), install `@intlayer/babel` alongside it and add the Babel plugins. Because Next.js uses SWC for transformation but still evaluates `babel.config.js` for plugin config, the Babel plugins run as a pre-pass before SWC.
+
+```bash packageManager="npm"
+npm install -D @intlayer/babel
+```
+
+```javascript fileName="babel.config.js"
+const {
+  intlayerPurgeBabelPlugin,
+  intlayerMinifyBabelPlugin,
+  getPurgePluginOptions,
+  getMinifyPluginOptions,
+} = require("@intlayer/babel");
+
+module.exports = {
+  presets: ["next/babel"],
+  plugins: [
+    // Purge: remove unused content fields from .intlayer/**/*.json
+    [intlayerPurgeBabelPlugin, getPurgePluginOptions()],
+    // Minify: rename content field keys in JSON + source code
+    [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],
+    // Note: intlayerOptimizeBabelPlugin is NOT needed here because
+    // @intlayer/swc handles the useIntlayer → useDictionary rewrite.
+  ],
+};
+```
 
  </Tab>
  <Tab value="vite">
 
 ### Vite
 
-Vite uses `@intlayer/babel` plugin which is included as dependency of `vite-intlayer`. The optimisation is enabled by default. Nothing else to do.
+Vite uses the `@intlayer/babel` plugin, which is included as a dependency of `vite-intlayer`. The full optimisation pipeline — import rewrite, purge, and minify — is enabled by default and requires no extra plugin registration.
+
+Enable purge and minify by setting the corresponding flags in `intlayer.config.ts`:
+
+```typescript fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  build: {
+    purge: true, // remove unused content fields from bundled JSON
+    minify: true, // rename content field keys to short aliases
+  },
+};
+
+export default config;
+```
 
  </Tab>
  <Tab value="webpack">
 
-### Webpack
+### Webpack (and Next.js with Babel)
 
-To enable bundle optimisation with Intlayer on Webpack, you need to install and configure the appropriate Babel (`@intlayer/babel`) or SWC (`@intlayer/swc`) plugin.
+Install `@intlayer/babel`:
 
 ```bash packageManager="npm"
 npm install -D @intlayer/babel
@@ -238,14 +320,37 @@ pnpm add -D @intlayer/babel
 bun add -d @intlayer/babel
 ```
 
-```typescript fileName="babel.config.js"
+Add all four plugins to `babel.config.js` in the correct order:
+
+```javascript fileName="babel.config.js"
 const {
-  getOptimizePluginOptions,
+  intlayerExtractBabelPlugin,
+  intlayerPurgeBabelPlugin,
+  intlayerMinifyBabelPlugin,
   intlayerOptimizeBabelPlugin,
+  getExtractPluginOptions,
+  getPurgePluginOptions,
+  getMinifyPluginOptions,
+  getOptimizePluginOptions,
 } = require("@intlayer/babel");
 
 module.exports = {
-  plugins: [[intlayerOptimizeBabelPlugin, getOptimizePluginOptions()]],
+  plugins: [
+    // Extract: compile .content.ts files → .intlayer/**/*.json
+    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
+
+    // Purge: remove unused fields from .intlayer/**/*.json
+    //    (reads the intlayer.config.ts build.purge flag)
+    [intlayerPurgeBabelPlugin, getPurgePluginOptions()],
+
+    // Minify: rename field keys in JSON + source code
+    //    (reads the intlayer.config.ts build.minify flag)
+    [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],
+
+    // Optimize: rewrite useIntlayer('key') → useDictionary(hash)
+    //    Must come last because it erases the dictionary key.
+    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
+  ],
 };
 ```
 
@@ -268,43 +373,48 @@ const config: IntlayerConfig = {
     importMode: "dynamic",
   },
   build: {
-    /**
-     * Minify the dictionaries to reduce the bundle size.
-     */
-     minify: true;
-
-    /**
-     * Purge the unused keys in a dictionaries
-     */
-     purge: true;
-
-    /**
-     * Indicates if the build should check TypeScript types
-     */
-    checkTypes: false;
+    // Replace useIntlayer() calls with direct dictionary imports at build-time.
+    // undefined = auto (enabled in production), true = always, false = never.
+    optimize: undefined,
+
+    // Rename content field keys in compiled dictionaries to short alphabetical
+    // aliases (e.g. title → a). Reduces JSON size; requires optimize.
+    minify: true,
+
+    // Remove content fields that are never accessed in the source code.
+    // Requires optimize.
+    purge: true,
   },
 };
 
 export default config;
 ```
 
-> Keeping the default option for `optimize` is recommended in the most majority of cases.
+> It is recommended to keep the default value (`undefined`) for `optimize` in most cases.
 
-> See doc configuration for more details: [Configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md)
+> See the configuration reference for all options: [Configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md)
 
 ### Build Options
 
-The following options are available under the `build` configuration object:
+| Property       | Type                   | Default     | Description                                                                                                                                                                                |
+| :------------- | :--------------------- | :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`optimize`** | `boolean \| undefined` | `undefined` | Enables the import rewrite pass. `undefined` = active in production builds only. `false` disables purge and minify as well.                                                                |
+| **`minify`**   | `boolean`              | `false`     | Renames content field keys in compiled JSON files to short alphabetical aliases. Rewrites matching property accesses in the source code as well. Has no effect when `optimize` is `false`. |
+| **`purge`**    | `boolean`              | `false`     | Removes content fields that are never statically accessed in the source code from the compiled JSON files. Has no effect when `optimize` is `false`.                                       |
 
-| Property       | Type      | Default     | Description                                                                                                                                                                                      |
-| :------------- | :-------- | :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **`optimize`** | `boolean` | `undefined` | Controls whether build optimisation is enabled. If `true`, Intlayer replaces dictionary calls with optimised injects. If `false`, optimisation is disabled. Ideally set to `true` in production. |
-| **`minify`**   | `boolean` | `false`     | Whether to minify the dictionaries to reduce the bundle size.                                                                                                                                    |
-| **`purge`**    | `boolean" | `false`     | Whether to purge the unused keys in dictionaries.                                                                                                                                                |
+### Minification (field key rename)
 
-### Minification
+`build.minify` does **not** minify your JavaScript bundle — your bundler handles that. Instead, it shrinks the compiled dictionary JSON files by replacing every user-defined content field key with a short alphabetical alias:
 
-Minifying dictionaries removes unnecessary whitespace, comments, and reduces the size of the JSON content. This is especially useful for large dictionaries.
+```
+// Before minification
+{ "title": "Hello", "subtitle": "World" }
+
+// After minification
+{ "a": "Hello", "b": "World" }
+```
+
+The same rename is applied to all property accesses in your source code, so `content.title` becomes `content.a` in the compiled output. The runtime behaviour is identical.
 
 ```typescript fileName="intlayer.config.ts"
 import type { IntlayerConfig } from "intlayer";
@@ -318,11 +428,13 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
-> Note: Minification is ignored if `optimize` is disabled or if the Visual Editor is enabled (as the editor needs the full content to allow editing).
+> Minification is skipped when `optimize` is `false` or when `editor.enabled` is `true` (the visual editor requires the original field names to allow editing).
+
+> Minification is also skipped for dictionaries loaded via `importMode: 'fetch'` because their JSON is served from a remote API using the original field names — renaming the client-side keys would break the server/client contract.
 
-### Purging
+### Purging (unused field removal)
 
-Purging ensures that only the keys actually used in your code are included in the final dictionary bundle. This can significantly reduce the size of your bundle if you have large dictionaries with many keys that are not used in every part of your application.
+`build.purge` analyses which content fields are actually accessed in your source code and removes all others from the compiled JSON files.
 
 ```typescript fileName="intlayer.config.ts"
 import type { IntlayerConfig } from "intlayer";
@@ -336,27 +448,43 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
-> Note: Purging is ignored if `optimize` is disabled.
+**Example:** a dictionary with five fields where only two are used:
+
+```
+// Before purge
+{ "title": "…", "subtitle": "…", "cta": "…", "footer": "…", "badge": "…" }
+
+// After purge (only title + subtitle accessed in source)
+{ "title": "…", "subtitle": "…" }
+```
+
+> Purge is skipped when `optimize` is `false` or when `editor.enabled` is `true`.
+
+> Purge is also conservatively skipped when a source file cannot be parsed, or when the result of `useIntlayer` is assigned to a variable and passed around in ways the static analyser cannot track (e.g. spread into an object, passed as a prop without destructuring). In those cases, the full dictionary is preserved.
 
 ### Import Mode
 
-For large applications, including several pages and locales, your JSON can represent a significant part of your bundle size. Intlayer allows you to control how dictionaries are loaded.
+For large applications, including several pages and locales, your JSON can represent an important part of your bundle size. Intlayer allows you to control how dictionaries are loaded using the `importMode` option.
+
+### Global definition
 
-The import mode can be defined by default globally in your `intlayer.config.ts` file.
+The import mode can be defined globally in your `intlayer.config.ts` file.
 
 ```typescript fileName="intlayer.config.ts"
 import type { IntlayerConfig } from "intlayer";
 
 const config: IntlayerConfig = {
-  build: {
-    minify: true,
+  dictionary: {
+    importMode: "dynamic", // Default is 'static'
   },
 };
 
 export default config;
 ```
 
-As well as for each dictionaries in your `.content.{{ts|tsx|js|jsx|mjs|cjs|json|jsonc|json5}}` files.
+### Per-dictionary definition
+
+You can override the import mode for individual dictionaries in their `.content.{{ts|tsx|js|jsx|mjs|cjs|json|jsonc|json5|md|mdx|yaml|yml}}` files.
 
 ```ts
 import { type Dictionary, t } from "intlayer";
@@ -372,28 +500,28 @@ const appContent: Dictionary = {
 export default appContent;
 ```
 
-| Property         | Type                               | Default    | Description                                                                                                      |
-| :--------------- | :--------------------------------- | :--------- | :--------------------------------------------------------------------------------------------------------------- |
-| **`importMode`** | `'static'`, `'dynamic'`, `'fetch'` | `'static'` | **Deprecated**: Use `dictionary.importMode` instead. Determines how dictionaries are loaded (see details below). |
+| Property         | Type                               | Default    | Description                                                                                              |
+| :--------------- | :--------------------------------- | :--------- | :------------------------------------------------------------------------------------------------------- |
+| **`importMode`** | `'static'`, `'dynamic'`, `'fetch'` | `'static'` | **Deprecated**: Use `dictionary.importMode` instead. Determines how dictionaries are loaded (see below). |
 
-The `importMode` setting dictates how the dictionary content is injected into your component.
-You can define it globally in the `intlayer.config.ts` file under the `dictionary` object, or you can overwrite it for a specific dictionary in its `.content.ts` file.
+The `importMode` setting determines how the dictionary's content is injected into your component. You can define it globally in `intlayer.config.ts` under the `dictionary` object, or override it on a per-dictionary basis in its `.content.ts` file.
 
 ### 1. Static Mode (`default`)
 
 In static mode, Intlayer replaces `useIntlayer` with `useDictionary` and injects the dictionary directly into the JavaScript bundle.
 
-- **Pros:** Instant rendering (synchronous), zero extra network requests during hydration.
+- **Pros:** Instant rendering (synchronous), zero additional network requests during hydration.
 - **Cons:** The bundle includes translations for **all** available languages for that specific component.
 - **Best for:** Single Page Applications (SPA).
 
-**Transformed Code Example:**
+**Transformed code example:**
 
 ```tsx
 // Your code
 const content = useIntlayer("my-key");
 
-// Optimised code (Static)
+// Optimised code illustration after transformation (Static)
+// This is for illustration only, the actual code will differ for optimisation reasons
 const content = useDictionary({
   key: "my-key",
   content: {
@@ -408,19 +536,20 @@ const content = useDictionary({
 
 ### 2. Dynamic Mode
 
-In dynamic mode, Intlayer replaces `useIntlayer` with `useDictionaryAsync`. This uses `import()` (Suspense-like mechanism) to lazy-load specifically the JSON for the current locale.
+In dynamic mode, Intlayer replaces the `useIntlayer` with `useDictionaryAsync`. This uses `import()` (a Suspense-like mechanism) to lazy-load specifically the JSON for the current locale.
 
-- **Pros:** **Locale-level tree shaking.** A user viewing the English version will _only_ download the English dictionary. The French dictionary is never loaded.
+- **Pros:** **Locale-level tree shaking.** A user viewing the English version will download _only_ the English dictionary. The French dictionary is never loaded.
 - **Cons:** Triggers a network request (asset fetch) per component during hydration.
 - **Best for:** Large text blocks, articles, or applications supporting many languages where bundle size is critical.
 
-**Transformed Code Example:**
+**Transformed code example:**
 
 ```tsx
 // Your code
 const content = useIntlayer("my-key");
 
-// Optimised code (Dynamic)
+// Optimised code illustration after transformation (Dynamic)
+// This is for illustration only, the actual code will differ for optimisation reasons
 const content = useDictionaryAsync({
   en: () =>
     import(".intlayer/dynamic_dictionary/my-key/en.json").then(
@@ -433,22 +562,41 @@ const content = useDictionaryAsync({
 });
 ```
 
-> When using `importMode: 'dynamic'`, if you have 100 components using `useIntlayer` on a single page, the browser will attempt 100 separate fetches. To avoid this "waterfall" of requests, group content into fewer `.content` files (e.g., one dictionary per page section) rather than one per atom component.
+> When using `importMode: 'dynamic'`, if you have 100 components using `useIntlayer` on a single page, the browser will attempt 100 separate fetches. To avoid this "waterfall" of requests, group content into fewer `.content` files (e.g. one dictionary per page section) instead of one per atom component. You can also use multiple `.content` files that use the same key. Intlayer will merge them into a single dictionary.
 
 ### 3. Fetch Mode
 
 Behaves similarly to Dynamic mode but attempts to fetch dictionaries from the Intlayer Live Sync API first. If the API call fails or the content is not marked for live updates, it falls back to the dynamic import.
 
+**Transformed code example:**
+
+```tsx
+// Your code
+const content = useIntlayer("my-key");
+
+// Optimised code illustration (Fetch)
+const content = useDictionaryAsync({
+  en: () =>
+    fetch("https://intlayer.my-domain.com/dictionary/my-key/en").then((res) =>
+      res.json()
+    ),
+  fr: () =>
+    fetch("https://intlayer.my-domain.com/dictionary/my-key/fr").then((res) =>
+      res.json()
+    ),
+});
+```
+
 > See CMS documentation for more details: [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_CMS.md)
 
-> In fetch mode, purge and minification can't be used.
+> In fetch mode, purge and minification are not applied because the JSON is served from a remote API using the original field names.
 
 ## Summary: Static vs Dynamic
 
-| Feature              | Static Mode                                   | Dynamic Mode                         |
-| :------------------- | :-------------------------------------------- | :----------------------------------- |
-| **JS Bundle Size**   | Larger (includes all langs for the component) | Smallest (only code, no content)     |
-| **Initial Load**     | Instant (Content is in bundle)                | Slight delay (Fetches JSON)          |
-| **Network Requests** | 0 extra requests                              | 1 request per dictionary             |
-| **Tree Shaking**     | Component-level                               | Component-level + Locale-level       |
-| **Best Use Case**    | UI Components, Small Apps                     | Pages with much text, Many Languages |
+| Feature              | Static Mode                                       | Dynamic Mode                     |
+| :------------------- | :------------------------------------------------ | :------------------------------- |
+| **JS Bundle Size**   | Larger (includes all languages for the component) | Smallest (code only, no content) |
+| **Initial Load**     | Instant (Content is in bundle)                    | Slight delay (Fetches JSON)      |
+| **Network Requests** | 0 extra requests                                  | 1 request per dictionary key     |
+| **Tree Shaking**     | Component-level                                   | Component-level + Locale-level   |
+| **Best Use Case**    | UI Components, Small Apps                         | Text-heavy pages, Many Languages |

package/docs/en-GB/configuration.md

@@ -681,16 +681,16 @@ routing: {
 
 When using cookie storage, you can configure additional cookie attributes:
 
-| Field      | Description                                                                              | Type                                                  |
-| ---------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------- |
-| `name`     | Cookie name. Default: `'INTLAYER_LOCALE'`                                                | `string`                                              |
-| `domain`   | Cookie domain. Default: `undefined`                                                      | `string`                                              |
-| `path`     | Cookie path. Default: `undefined`                                                        | `string`                                              |
-| `secure`   | Require HTTPS. Default: `undefined`                                                      | `boolean`                                             |
-| `httpOnly` | HTTP-only flag. Default: `undefined`                                                     | `boolean`                                             |
-| `sameSite` | SameSite policy.                                                                         | `'strict'` &#124; <br/> `'lax'` &#124; <br/> `'none'` |
-| `expires`  | Expiration date or days. Default: `undefined`                                            | `Date` &#124; <br/> `number`                          |
-| `maxAge`   | Lifetime in seconds from creation. Takes precedence over `expires`. Default: `undefined` | `number`                                              |
+| Field      | Description                                                                                                 | Type                                                  |
+| ---------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
+| `name`     | Cookie name. Default: `'INTLAYER_LOCALE'`                                                                   | `string`                                              |
+| `domain`   | Cookie domain. Default: `undefined`                                                                         | `string`                                              |
+| `path`     | Cookie path. Default: `undefined`                                                                           | `string`                                              |
+| `secure`   | Require HTTPS. Default: `undefined`                                                                         | `boolean`                                             |
+| `httpOnly` | HTTP-only flag. Default: `undefined`                                                                        | `boolean`                                             |
+| `sameSite` | SameSite policy.                                                                                            | `'strict'` &#124; <br/> `'lax'` &#124; <br/> `'none'` |
+| `expires`  | A `number` is days from creation; a `Date` (or ISO date string) is an absolute expiry. Default: `undefined` | `Date` &#124; <br/> `number` &#124; <br/> `string`    |
+| `maxAge`   | Lifetime in seconds from creation. Takes precedence over `expires`. Default: `undefined`                    | `number`                                              |
 
 #### Locale Storage Attributes