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

package/docs/fr/dynamic_dictionaries/variants.md

@@ -1,13 +1,15 @@
 ---
 createdAt: 2026-06-12
-updatedAt: 2026-06-12
+updatedAt: 2026-06-26
 title: Variantes
-description: Utilisez le champ de métadonnées de variante dans les fichiers de contenu Intlayer pour déclarer des alternatives de contenu nommées (tests A/B, bannières saisonnières, texte avec feature flags) et basculez entre elles au moment de l'exécution sans modification de code.
+description: Utilisez le champ de métadonnées variant dans les fichiers de contenu Intlayer pour déclarer des alternatives de contenu nommées ou structurées — tests A/B, bannières saisonnières, contenu sous feature flag, enregistrements de CMS, contenu propre à un utilisateur — et basculer entre elles à l'exécution sans changement de code.
 keywords:
   - Variantes
   - Tests A/B
   - Feature Flags
-  - Contenu Dynamique
+  - Contenu dynamique
+  - Enregistrements dynamiques
+  - CMS
   - Intlayer
   - Internationalisation
 slugs:
@@ -17,15 +19,25 @@ slugs:
 history:
   - version: 9.0.0
     date: 2026-06-12
-    changes: "Lancement de la fonctionnalité des variantes de dictionnaires"
+    changes: "Sortie de la fonctionnalité des variantes"
+  - version: 9.1.0
+    date: 2026-06-26
+    changes: "`variant` accepte désormais une chaîne ou un objet — les anciens `meta` / enregistrements dynamiques se déclarent comme variantes objet"
 author: aymericzip
 ---
 
 # Variantes
 
-Une **variante** est un ensemble de fichiers de contenu qui partagent la même clé de dictionnaire (`key`) mais portent chacun un nom de variante (`variant`) différent. Intlayer sert le fichier approprié en fonction du sélecteur passé à `useIntlayer`.
+Une **variante** est un ensemble de fichiers de contenu qui partagent la même clé de dictionnaire (`key`) mais portent chacun une valeur `variant` différente. Intlayer sert le fichier approprié en fonction du sélecteur passé à `useIntlayer`.
 
-## Déclarer des variantes
+La valeur `variant` peut prendre **deux formes** :
+
+- **Une chaîne** — une seule alternative nommée (tests A/B, bannières saisonnières, feature flags).
+- **Un objet** — un discriminant structuré adressé par un ensemble de champs (enregistrements de CMS, contenu propre à un utilisateur, tout contenu indexé par un identifiant opaque). L'objet entier constitue l'identité : le sélecteur doit fournir un objet **égal** pour résoudre l'entrée.
+
+> La forme objet remplace l'ancien champ `meta`. Partout où vous écriviez `meta: { id, … }`, écrivez `variant: { id, … }`, et sélectionnez-la avec `{ variant: { id, … } }`.
+
+## Variantes nommées (chaîne)
 
 Chaque fichier représente une alternative nommée. Omettre `variant` (ou le définir sur `"default"`) le marque comme valeur par défaut (fallback).
 
@@ -65,9 +77,9 @@ const dictionary = {
 export default dictionary;
 ```
 
-## Consommer des variantes
+### Consommer des variantes nommées
 
-### Variante par défaut
+#### Variante par défaut
 
 <Tabs group="framework">
   <Tab label="React" value="react">
@@ -209,7 +221,7 @@ export default dictionary;
   </Tab>
 </Tabs>
 
-### Variante nommée
+#### Variante nommée
 
 ```tsx
 const { headline, cta } = useIntlayer("hero-banner", {
@@ -217,7 +229,7 @@ const { headline, cta } = useIntlayer("hero-banner", {
 });
 ```
 
-### Variante nommée avec locale explicite
+#### Variante nommée avec locale explicite
 
 ```tsx
 const content = useIntlayer("hero-banner", {
@@ -226,9 +238,255 @@ const content = useIntlayer("hero-banner", {
 });
 ```
 
-## Cas d'utilisation typiques
+## Variantes objet (structurées)
+
+Une variante objet adresse le contenu par un ensemble arbitraire de paires clé-valeur déclarées dans le champ `variant` — permettant de modéliser des enregistrements de CMS, du contenu propre à un utilisateur ou tout contenu dont la clé est un identifiant opaque. L'**objet entier** constitue l'identité : le sélecteur doit fournir un objet égal pour que l'entrée soit résolue.
+
+```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;
+```
+
+### Consommer des variantes objet
+
+Passez l'objet correspondant à `variant`. Chaque champ déclaré sur le dictionnaire doit être fourni et égal ; sinon le résultat est `null`. L'ordre des champs n'a pas d'importance.
+
+<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>
+
+#### Avec une locale explicite
+
+```tsx
+const content = useIntlayer("product", {
+  variant: { id: "prod_abc", userId: "user_123" },
+  locale: "fr",
+});
+```
+
+#### Champ manquant — aucune correspondance
+
+```ts
+// Renvoie null : `userId` est manquant, donc l'objet ne correspond pas à la variante déclarée
+const content = useIntlayer("product", { variant: { id: "prod_abc" } });
+```
+
+## Mode de chargement
+
+Les variantes objet sont souvent chargées de façon différée. Définissez `importMode` sur le dictionnaire pour contrôler ce comportement :
+
+```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;
+```
+
+Voir [optimisation du bundle](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/bundle_optimization.md) pour les détails sur les modes `static`, `dynamic` et `fetch`.
+
+## Cas d'usage typiques
 
-- Tests A/B pilotés par une clé d'expérimentation
-- Bannières promotionnelles ou saisonnières
-- Messages soumis à des feature flags
-- Campagnes marketing spécifiques à une zone géographique
+- Tests A/B de texte pilotés par une clé d'expérience
+- Bannières saisonnières ou promotionnelles
+- Messages sous feature flag
+- Campagnes marketing spécifiques à une locale
+- Texte marketing par produit géré dans un CMS
+- Contenu propre à un utilisateur ou à un compte
+- Tout contenu indexé par un identifiant opaque à l'exécution

package/docs/fr/intlayer_with_analog.md

@@ -207,7 +207,11 @@ import analog from "@analogjs/platform";
 export default defineConfig(() => ({
   plugins: [
     analog(),
-    intlayer(), // Ajouter le plugin Intlayer
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 }));
 ```

package/docs/fr/intlayer_with_astro.md

@@ -517,6 +517,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Compilateur Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 Mettez à jour votre fichier `vite.config.ts` pour inclure le plugin `intlayerCompiler` :
 
 ```ts fileName="vite.config.ts"
@@ -526,7 +528,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Ajoute le plugin du compilateur
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/fr/intlayer_with_astro_lit.md

@@ -601,6 +601,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Compilateur Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 Mettez à jour votre fichier `vite.config.ts` pour inclure le plugin `intlayerCompiler` :
 
 ```ts fileName="vite.config.ts"
@@ -610,7 +612,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Ajoute le plugin du compilateur
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/fr/intlayer_with_astro_preact.md

@@ -556,6 +556,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Compilateur Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 Mettez à jour votre fichier `vite.config.ts` pour inclure le plugin `intlayerCompiler` :
 
 ```ts fileName="vite.config.ts"
@@ -565,7 +567,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Ajoute le plugin du compilateur
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/fr/intlayer_with_astro_react.md

@@ -553,6 +553,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Compilateur Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 Mettez à jour votre fichier `vite.config.ts` pour inclure le plugin `intlayerCompiler` :
 
 ```ts fileName="vite.config.ts"
@@ -562,7 +564,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Ajoute le plugin du compilateur
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/fr/intlayer_with_astro_solid.md

@@ -553,6 +553,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Compilateur Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 Mettez à jour votre fichier `vite.config.ts` pour inclure le plugin `intlayerCompiler` :
 
 ```ts fileName="vite.config.ts"
@@ -562,7 +564,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Ajoute le plugin du compilateur
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/fr/intlayer_with_astro_svelte.md

@@ -557,6 +557,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Compilateur Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 Mettez à jour votre fichier `vite.config.ts` pour inclure le plugin `intlayerCompiler` :
 
 ```ts fileName="vite.config.ts"
@@ -566,7 +568,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Ajoute le plugin du compilateur
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/fr/intlayer_with_astro_vanilla.md

@@ -529,6 +529,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Compilateur Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 Mettez à jour votre fichier `vite.config.ts` pour inclure le plugin `intlayerCompiler` :
 
 ```ts fileName="vite.config.ts"
@@ -538,7 +540,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Ajoute le plugin du compilateur
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/fr/intlayer_with_astro_vue.md

@@ -567,6 +567,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Compilateur Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 Mettez à jour votre fichier `vite.config.ts` pour inclure le plugin `intlayerCompiler` :
 
 ```ts fileName="vite.config.ts"
@@ -576,7 +578,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Ajoute le plugin du compilateur
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/fr/intlayer_with_lynx+react.md

@@ -223,6 +223,8 @@ if (import.meta.webpackHot) {
 Créez des fichiers de **déclaration de contenu** n'importe où dans votre projet (généralement dans `src/`), en utilisant l'un des formats d'extension pris en charge par Intlayer :
 
 - `.content.json`
+- `.content.jsonc`
+- `.content.json5`
 - `.content.ts`
 - `.content.tsx`
 - `.content.js`
@@ -230,7 +232,10 @@ Créez des fichiers de **déclaration de contenu** n'importe où dans votre proj
 - `.content.mjs`
 - `.content.mjx`
 - `.content.cjs`
-- `.content.cjx`
+- `.content.md`
+- `.content.mdx`
+- `.content.yaml`
+- `.content.yml`
 - etc.
 
 Exemple :

package/docs/fr/intlayer_with_nextjs_16.md

@@ -1045,6 +1045,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Compilateur Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 ```bash packageManager="npm"
 npm install @intlayer/babel --save-dev
 ```

package/docs/fr/intlayer_with_nextjs_compiler.md

@@ -585,6 +585,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Compilateur Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 ```bash packageManager="npm"
 npm install @intlayer/babel --save-dev
 ```

package/docs/fr/intlayer_with_react_native+expo.md

@@ -261,6 +261,8 @@ export default RootLayout;
 Créez des fichiers de **déclaration de contenu** n'importe où dans votre projet (généralement dans `src/`), en utilisant l'un des formats d'extension pris en charge par Intlayer :
 
 - `.content.json`
+- `.content.jsonc`
+- `.content.json5`
 - `.content.ts`
 - `.content.tsx`
 - `.content.js`
@@ -268,7 +270,10 @@ Créez des fichiers de **déclaration de contenu** n'importe où dans votre proj
 - `.content.mjs`
 - `.content.mjx`
 - `.content.cjs`
-- `.content.cjx`
+- `.content.md`
+- `.content.mdx`
+- `.content.yaml`
+- `.content.yml`
 - etc.
 
 > **Expo Router (web) : gardez les fichiers `.content.*` en dehors du répertoire `app/`.** Expo Router traite chaque fichier JavaScript/TypeScript dans `app/` comme une route. Sur le web, sa découverte de routes scanne directement le système de fichiers et **ne respecte pas** le `resolver.blockList` de Metro, donc un `*.content.ts` co-localisé est enregistré comme une route. Un fichier tel que `app/(tabs)/_layout.content.ts` est même analysé comme un layout (la partie `.content` est lue comme un suffixe de plateforme), ce qui entre en conflit avec le vrai `_layout.tsx` et renvoie une erreur :

package/docs/fr/intlayer_with_react_router_v7.md

@@ -636,6 +636,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Compilateur Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 Mettez à jour votre fichier `vite.config.ts` pour inclure le plugin `intlayerCompiler` :
 
 ```ts fileName="vite.config.ts"
@@ -645,7 +647,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Ajoute le plugin du compilateur
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/fr/intlayer_with_react_router_v7_fs_routes.md

@@ -683,6 +683,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Compilateur Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 Mettez à jour votre fichier `vite.config.ts` pour inclure le plugin `intlayerCompiler` :
 
 ```ts fileName="vite.config.ts"
@@ -692,7 +694,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Ajoute le plugin du compilateur
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/fr/intlayer_with_storybook.md

@@ -190,7 +190,13 @@ const config: StorybookConfig = {
     } as const;
 
     const viteConfig = defineConfig(() => ({
-      plugins: [intlayer()],
+      plugins: [
+        intlayer({
+          proxy: {
+            ignore: (req) => req.url?.startsWith("/api"),
+          },
+        }),
+      ],
     }));
 
     return mergeConfig(baseConfig, viteConfig(env));

package/docs/fr/intlayer_with_svelte_kit.md

@@ -614,14 +614,17 @@ Pour ajouter un proxy backend à votre application SvelteKit, vous pouvez utilis
 
 ```ts fileName="vite.config.ts"
 import { defineConfig } from "vite";
-import { intlayer, intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 import { sveltekit } from "@sveltejs/kit/vite";
 
 // https://vitejs.dev/config/
 export default defineConfig({
   plugins: [
-    intlayerProxy(), // should be placed first
-    intlayer(),
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
     sveltekit(),
   ],],
 });
@@ -719,6 +722,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Compilateur Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 Mettez à jour votre fichier `vite.config.ts` pour inclure le plugin `intlayerCompiler` :
 
 ```ts fileName="vite.config.ts"
@@ -728,7 +733,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Ajoute le plugin du compilateur
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```