@intlayer/docs 8.12.5-canary.0 → 9.0.0-canary.11

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

@@ -1,31 +1,43 @@
 ---
 createdAt: 2026-06-12
-updatedAt: 2026-06-12
+updatedAt: 2026-06-26
 title: Variants
-description: Use the variant metadata field in Intlayer content files to declare named content alternatives — A/B tests, seasonal banners, feature-flagged copy — and switch between them at runtime without code changes.
+description: Use the variant metadata field in Intlayer content files to declare named or structured content alternatives — A/B tests, seasonal banners, feature-flagged copy, CMS records, user-specific content — and switch between them at runtime without code changes.
 keywords:
   - Variants
   - A/B Testing
   - Feature Flags
   - Dynamic Content
+  - Dynamic Records
+  - CMS
   - Intlayer
-  - Internationalisation
+  - Internationalization
 slugs:
   - doc
   - concept
   - variants
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-12
     changes: "Release of the variants feature"
+  - version: 9.1.0
+    date: 2026-06-26
+    changes: "`variant` now accepts a string or an object — the former `meta` / dynamic records are declared as object variants"
 author: aymericzip
 ---
 
 # Variants
 
-A **variant** is a set of content files that share the same dictionary `key` but each carry a different `variant` name. Intlayer serves the appropriate file based on the selector passed to `useIntlayer`.
+A **variant** is a set of content files that share the same dictionary `key` but each carry a different `variant` value. Intlayer serves the appropriate file based on the selector passed to `useIntlayer`.
 
-## Declaring variants
+The `variant` value can take **two forms**:
+
+- **A string** — a single named alternative (A/B tests, seasonal banners, feature flags).
+- **An object** — a structured discriminator addressed by a set of fields (CMS records, user-specific copy, any content keyed by an opaque ID). The whole object is the identity: the selector must provide an **equal** object to resolve the entry.
+
+> The object form replaces the former `meta` field. Anywhere you previously wrote `meta: { id, … }`, write `variant: { id, … }`, and select it with `{ variant: { id, … } }`.
+
+## Named (string) variants
 
 Each file represents one named alternative. Omitting `variant` (or setting it to `"default"`) marks it as the fallback.
 
@@ -65,9 +77,9 @@ const dictionary = {
 export default dictionary;
 ```
 
-## Consuming variants
+### Consuming named variants
 
-### Default variant
+#### Default variant
 
 <Tabs group="framework">
   <Tab label="React" value="react">
@@ -209,7 +221,7 @@ export default dictionary;
   </Tab>
 </Tabs>
 
-### Named variant
+#### Named variant
 
 ```tsx
 const { headline, cta } = useIntlayer("hero-banner", {
@@ -217,18 +229,264 @@ const { headline, cta } = useIntlayer("hero-banner", {
 });
 ```
 
-### Named variant with explicit locale
+#### Named variant with explicit locale
 
 ```tsx
 const content = useIntlayer("hero-banner", {
   variant: "black_friday",
-  locale: "en-GB",
+  locale: "fr",
 });
 ```
 
+## Object (structured) variants
+
+An object variant addresses content by an arbitrary set of key-value pairs declared in the `variant` field — making it possible to model CMS records, user-specific copy, or any content whose key is an opaque ID. The **whole object** is the identity: the selector must provide an equal object for the entry to resolve.
+
+```ts fileName="product.abc.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+import { t, type Dictionary } from "intlayer";
+
+const dictionary = {
+  key: "product",
+  variant: { id: "prod_abc", userId: "user_123" },
+  content: {
+    name: t({ en: "Widget Pro", fr: "Widget Pro" }),
+    description: t({ en: "The best widget.", fr: "Le meilleur widget." }),
+  },
+} satisfies Dictionary;
+
+export default dictionary;
+```
+
+```ts fileName="product.abcd.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+import { t, type Dictionary } from "intlayer";
+
+const dictionary = {
+  key: "product",
+  variant: { id: "prod_abcd", userId: "user_123" },
+  content: {
+    name: t({ en: "Widget Lite", fr: "Widget Lite" }),
+    description: t({ en: "A lighter option.", fr: "Une option plus légère." }),
+  },
+} satisfies Dictionary;
+
+export default dictionary;
+```
+
+### Consuming object variants
+
+Pass the matching object to `variant`. Every field declared on the dictionary must be provided and equal; otherwise the result is `null`. Field order does not matter.
+
+<Tabs group="framework">
+  <Tab label="React" value="react">
+    ```tsx fileName="Product.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { useIntlayer } from "react-intlayer";
+
+    export const Product = ({
+      productId,
+      userId,
+    }: {
+      productId: string;
+      userId: string;
+    }) => {
+      const content = useIntlayer("product", {
+        variant: { id: productId, userId },
+      });
+
+      if (!content) return null;
+
+      return <p>{content.description}</p>;
+    };
+    ```
+
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+    ```tsx fileName="Product.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { useIntlayer } from "next-intlayer";
+
+    export const Product = ({
+      productId,
+      userId,
+    }: {
+      productId: string;
+      userId: string;
+    }) => {
+      const content = useIntlayer("product", {
+        variant: { id: productId, userId },
+      });
+
+      if (!content) return null;
+
+      return <p>{content.description}</p>;
+    };
+    ```
+
+  </Tab>
+  <Tab label="Vue" value="vue">
+    ```vue fileName="Product.vue" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    <script setup>
+    import { useIntlayer } from "vue-intlayer";
+
+    const props = defineProps({
+      productId: String,
+      userId: String,
+    });
+
+    const content = useIntlayer("product", {
+      variant: { id: props.productId, userId: props.userId },
+    });
+    </script>
+
+    <template>
+      <p v-if="content">{{ content.description }}</p>
+    </template>
+    ```
+
+  </Tab>
+  <Tab label="Svelte" value="svelte">
+    ```svelte fileName="Product.svelte" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    <script lang="ts">
+    import { useIntlayer } from "svelte-intlayer";
+
+    export let productId: string;
+    export let userId: string;
+
+    const content = useIntlayer("product", {
+      variant: { id: productId, userId },
+    });
+    </script>
+
+    {#if $content}
+      <p>{$content.description}</p>
+    {/if}
+    ```
+
+  </Tab>
+  <Tab label="Preact" value="preact">
+    ```tsx fileName="Product.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { useIntlayer } from "preact-intlayer";
+
+    export const Product = ({
+      productId,
+      userId,
+    }: {
+      productId: string;
+      userId: string;
+    }) => {
+      const content = useIntlayer("product", {
+        variant: { id: productId, userId },
+      });
+
+      if (!content) return null;
+
+      return <p>{content.description}</p>;
+    };
+    ```
+
+  </Tab>
+  <Tab label="Solid" value="solid">
+    ```tsx fileName="Product.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { useIntlayer } from "solid-intlayer";
+
+    export const Product = (props: {
+      productId: string;
+      userId: string;
+    }) => {
+      const content = useIntlayer("product", {
+        variant: { id: props.productId, userId: props.userId },
+      });
+
+      return (
+        <>
+          {content() && <p>{content().description}</p>}
+        </>
+      );
+    };
+    ```
+
+  </Tab>
+  <Tab label="Angular" value="angular">
+    ```typescript fileName="product.component.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { Component, Input, OnInit } from "@angular/core";
+    import { useIntlayer } from "angular-intlayer";
+
+    @Component({
+      selector: "app-product",
+      template: `
+        @if (content()) {
+          <p>{{ content().description }}</p>
+        }
+      `,
+    })
+    export class ProductComponent implements OnInit {
+      @Input() productId!: string;
+      @Input() userId!: string;
+
+      content: any;
+
+      ngOnInit() {
+        this.content = useIntlayer("product", {
+          variant: { id: this.productId, userId: this.userId },
+        });
+      }
+    }
+    ```
+
+  </Tab>
+  <Tab label="Vanilla JS" value="vanilla">
+    ```javascript fileName="product.js"
+    import { useIntlayer } from "vanilla-intlayer";
+
+    const content = useIntlayer("product", {
+      variant: { id: "prod_abcd", userId: "user_123" },
+    });
+
+    if (content) {
+      document.body.innerHTML = `<p>${content.description}</p>`;
+    }
+    ```
+
+  </Tab>
+</Tabs>
+
+#### With explicit locale
+
+```tsx
+const content = useIntlayer("product", {
+  variant: { id: "prod_abc", userId: "user_123" },
+  locale: "fr",
+});
+```
+
+#### Missing field — no match
+
+```ts
+// Returns null: `userId` is missing, so the object does not match the declared variant
+const content = useIntlayer("product", { variant: { id: "prod_abc" } });
+```
+
+## Loading mode
+
+Object variants are often loaded lazily. Set `importMode` on the dictionary to control this:
+
+```ts contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+const dictionary = {
+  key: "product",
+  importMode: "fetch", // or "dynamic"
+  variant: { id: "prod_abc", userId: "user_123" },
+  content: { … },
+} satisfies Dictionary;
+
+export default dictionary;
+```
+
+See [bundle optimization](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/bundle_optimization.md) for details on `static`, `dynamic`, and `fetch` modes.
+
 ## Typical use-cases
 
 - A/B copy tests driven by an experiment key
 - Seasonal or promotional banners
 - Feature-flagged messaging
 - Locale-specific marketing campaigns
+- Per-product marketing copy managed in a CMS
+- User-specific or account-specific content
+- Any content keyed by an opaque runtime ID

package/docs/en-GB/formatters.md

@@ -400,6 +400,8 @@ date(new Date(), "short"); // e.g., "08/02/25, 14:30"
 date("2025-08-02T14:30:00Z", { locale: "fr", month: "long", day: "numeric" }); // "2 août"
 ```
 
+### Additional Intl Features
+
 ### `relativeTime(from, to = new Date(), options?)`
 
 Formats relative time between two instants with `Intl.RelativeTimeFormat`.
@@ -457,6 +459,8 @@ compact(1200); // "1.2K"
 compact("1000000", { locale: "fr", compactDisplay: "long" }); // "1 million"
 ```
 
+## Locale Utilities
+
 ### `list(values, options?)`
 
 Formats an array of values into a localised list string using `Intl.ListFormat`.
@@ -476,6 +480,17 @@ list(["red", "green", "blue"], { locale: "fr", type: "disjunction" }); // "rouge
 list([1, 2, 3], { type: "unit" }); // "1, 2, 3"
 ```
 
+### `getLocaleLang(locale?)`
+
+Extracts the language code from a locale string:
+
+```ts
+import { getLocaleLang } from "intlayer";
+
+getLocaleLang("en-US"); // "en"
+getLocaleLang("fr-CA"); // "fr"
+```
+
 ## Notes
 
 - All helpers accept `string` inputs; they are internally coerced to numbers or dates.
@@ -592,6 +607,20 @@ import {
 
 > These hooks will consider the locale from the `IntlayerProvider` or `IntlayerServerProvider`
 
+### `getHTMLTextDir(locale?)`
+
+Returns the text direction for a locale:
+
+```ts
+import { getHTMLTextDir } from "intlayer";
+
+getHTMLTextDir("en-US"); // "ltr"
+getHTMLTextDir("ar"); // "rtl"
+getHTMLTextDir("he"); // "rtl"
+```
+
+## Content Handling Utilities
+
 ### Vue
 
 Client components:
@@ -610,3 +639,33 @@ import {
 ```
 
 > These composables will consider the locale from the injected `IntlayerProvider`
+
+### `getTranslation(languageContent, locale?, fallback?)`
+
+Extracts content for a specific locale:
+
+```ts
+import { getTranslation } from "intlayer";
+
+const content = getTranslation(
+  { en: "Hello", fr: "Bonjour", de: "Hallo" },
+  "fr",
+  true
+); // "Bonjour"
+```
+
+### `getIntlayer(dictionaryKey, locale?, plugins?)`
+
+Retrieves and transforms content from a dictionary:
+
+```ts
+import { getIntlayer } from "intlayer";
+
+const content = getIntlayer("common", "fr");
+```
+
+## Notes
+
+- All helpers accept `string` inputs; they are internally coerced to numbers or dates.
+- Locale defaults to your configured `internationalization.defaultLocale` if not provided.
+- These utilities are thin wrappers; for advanced formatting, pass through the standard `Intl` options.

package/docs/en-GB/how_works_intlayer.md

@@ -22,6 +22,10 @@ author: aymericzip
 
 # How Intlayer Works
 
+## Table of Contents
+
+<TOC/>
+
 ## Overview
 
 The main idea behind Intlayer is to adopt a per-component content management. So the idea behind Intlayer is to allow you to declare your content anywhere in your codebase, as in the same directory as your component.
@@ -227,22 +231,6 @@ The `@intlayer/editor-react` package provides states, contexts, hooks and compon
 
 ### @intlayer/babel
 
-The `@intlayer/babel` package provides tools that optimise bundling of dictionaries for Vite and Webpack based applications.
-
-### @intlayer/swc
-
-The `@intlayer/swc` package provides tools that optimise bundling of dictionaries for Next.js applications.
-
-### @intlayer/api
-
-The `@intlayer/api` package is an API SDK to interact with the backend.
-
-### @intlayer/editor-react
-
-The `@intlayer/editor-react` package provides states, contexts, hooks and components to interface a React application with the Intlayer editor.
-
-### @intlayer/babel
-
 The `@intlayer/babel` package provides tools that optimize bundling of dictionaries for Vite and Webpack based applications.
 
 ### @intlayer/swc

package/docs/en-GB/intlayer_CMS.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-08-23
-updatedAt: 2025-08-23
+updatedAt: 2026-06-30
 title: Intlayer CMS | Externalise your content into the Intlayer CMS
 description: Externalise your content into the Intlayer CMS to delegate the management of your content to your team.
 keywords:
@@ -18,6 +18,9 @@ slugs:
   - cms
 youtubeVideo: https://www.youtube.com/watch?v=UDDTnirwi_4
 history:
+  - version: 9.0.0
+    date: 2026-06-30
+    changes: "Add Self-Hosting section"
   - version: 6.0.1
     date: 2025-09-22
     changes: "Add live sync documentation"
@@ -40,6 +43,12 @@ For this, Intlayer introduces the concept of 'remote dictionaries'.
 
 ![Intlayer CMS Interface](https://github.com/aymericzip/intlayer/blob/main/docs/assets/CMS.png)
 
+## Table of Contents
+
+<TOC/>
+
+---
+
 ## Understanding remote dictionaries
 
 Intlayer distinguishes between 'local' and 'remote' dictionaries.
@@ -367,6 +376,18 @@ Notes and constraints:
 - The `live` flag is evaluated for each dictionary at build time. If remote content was not flagged `live=true` during build, you must rebuild to enable Live Sync for that dictionary.
 - The live sync server must be able to write to `.intlayer`. In containers, ensure write access to `/.intlayer`.
 
+## Self-Hosting
+
+Intlayer can run entirely on your own infrastructure. A one-liner bootstraps the full stack (dashboard, API, database, object storage, and email) with Docker Compose:
+
+```sh
+curl -fsSL https://intlayer.org/install.sh | sh
+```
+
+For the complete setup guide, environment variable reference, upgrade instructions, and backup/restore procedures, see the [Self-Hosting Guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/self_hosting.md).
+
+---
+
 ## Debug
 
 If you encounter any issues with the CMS, check the following:

package/docs/en-GB/intlayer_with_adonisjs.md

@@ -59,24 +59,40 @@ See [Application Template](https://github.com/aymericzip/intlayer-adonis-templat
 
 To begin using `adonis-intlayer`, install the package using npm:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> the `--interactive` flag is optional. Use `intlayer-cli init` if you're an AI agent.
+
+> This command will detect your environment and install the required packages. For example:
+
 ```bash packageManager="npm"
 npm install intlayer adonis-intlayer
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer adonis-intlayer
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer adonis-intlayer
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer adonis-intlayer
-bun x intlayer init
 ```
 
 ### Setup

package/docs/en-GB/intlayer_with_analog.md

@@ -118,24 +118,40 @@ See [Application Template](https://github.com/aymericzip/intlayer-analog-templat
 
 Install the necessary packages using npm:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> the `--interactive` flag is optional. Use `intlayer-cli init` if you're an AI agent.
+
+> This command will detect your environment and install the required packages. For example:
+
 ```bash packageManager="npm"
 npm install intlayer angular-intlayer vite-intlayer
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer angular-intlayer vite-intlayer
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer angular-intlayer vite-intlayer
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer angular-intlayer vite-intlayer
-bun x intlayer init
 ```
 
 - **intlayer**
@@ -191,7 +207,11 @@ import analog from "@analogjs/platform";
 export default defineConfig(() => ({
   plugins: [
     analog(),
-    intlayer(), // Add the Intlayer plugin
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 }));
 ```

package/docs/en-GB/intlayer_with_angular_19.md

@@ -124,28 +124,44 @@ See [Application Template](https://github.com/aymericzip/intlayer-angular-19-tem
 
 Install the necessary packages using npm:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> the `--interactive` flag is optional. Use `intlayer-cli init` if you're an AI agent.
+
+> This command will detect your environment and install the required packages. For example:
+
 ```bash packageManager="npm"
 npm install intlayer angular-intlayer
 npm install @angular-builders/custom-webpack --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer angular-intlayer
 pnpm add @angular-builders/custom-webpack --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer angular-intlayer
 yarn add @angular-builders/custom-webpack --save-dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer angular-intlayer
 bun add @angular-builders/custom-webpack --dev
-bun x intlayer init
 ```
 
 - **intlayer**