@intlayer/docs 9.1.0 → 9.1.2

package/docs/es/dynamic_dictionaries/variants.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-06-12
-updatedAt: 2026-06-26
+updatedAt: 2026-08-04
 title: Variantes
 description: Use el campo de metadatos variant en los archivos de contenido de Intlayer para declarar alternativas de contenido con nombre o estructuradas — pruebas A/B, banners de temporada, copia con feature flag, registros de CMS, contenido específico de usuario — y cambiar entre ellas en tiempo de ejecución sin cambios de código.
 keywords:
@@ -23,6 +23,12 @@ history:
   - version: 9.1.0
     date: 2026-06-26
     changes: "`variant` ahora acepta una cadena o un objeto — los antiguos `meta` / registros dinámicos se declaran como variantes de objeto"
+  - version: 9.1.1
+    date: 2026-07-31
+    changes: "Una variante declara solo las claves que anula; las variantes no declaradas recurren a la entrada por defecto"
+  - version: 9.1.2
+    date: 2026-08-04
+    changes: "Los proveedores aceptan una prop `variant` ambiental; los selectores aceptan una cadena de preferencia ordenada"
 author: aymericzip
 ---
 
@@ -77,6 +83,37 @@ const dictionary = {
 export default dictionary;
 ```
 
+### Variantes parciales
+
+Una variante declara **solo las claves que anula**; el resto se hereda de la entrada por defecto.
+
+```ts fileName="hero-banner.summer.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+import { t, type Dictionary } from "intlayer";
+
+const dictionary = {
+  key: "hero-banner",
+  variant: "summer",
+  content: {
+    headline: t({
+      en: "Build faster all summer",
+      fr: "Développez plus vite tout l'été",
+    }),
+  },
+} satisfies Dictionary;
+
+export default dictionary;
+```
+
+```tsx
+useIntlayer("hero-banner", { variant: "summer" });
+// → { headline: "Développez plus vite tout l'été", cta: "Commencer" } — `cta` heredado
+
+useIntlayer("hero-banner", { variant: "never-declared" });
+// → la entrada por defecto
+```
+
+Por lo tanto, solo debe agregar un archivo de variante donde la redacción realmente difiera. Una clave se resuelve en `null` solo cuando declara variantes pero ninguna entrada por defecto.
+
 ### Consumir variantes con nombre
 
 #### Variante por defecto
@@ -464,6 +501,176 @@ const content = useIntlayer("product", {
 const content = useIntlayer("product", { variant: { id: "prod_abc" } });
 ```
 
+## Variante ambiental
+
+Algunas dimensiones de variante son fijas durante toda una sesión: el inquilino, el tipo de centro, el nivel de plan. Se resuelven una sola vez, y ningún componente debería tener que pasarlas a mano.
+
+> No envuelvas `useIntlayer` en tu propio hook para inyectarlas. La optimización en tiempo de compilación solo reescribe una llamada literal `useIntlayer("key")` importada del paquete del framework, por lo que nada detrás de un wrapper se incluye en el bundle.
+
+En su lugar, declara la variante una sola vez en el proveedor, exactamente igual que `locale`:
+
+<Tabs group="framework">
+  <Tab label="React" value="react">
+    ```tsx fileName="App.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { IntlayerProvider } from "react-intlayer";
+
+    export const App = ({ locale, schoolType }) => (
+      <IntlayerProvider locale={locale} variant={schoolType}>
+        <Hero />
+      </IntlayerProvider>
+    );
+    ```
+
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+    ```tsx fileName="layout.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { IntlayerServerProvider } from "next-intlayer/server";
+    import { IntlayerClientProvider } from "next-intlayer";
+
+    export default async function Layout({ children, params }) {
+      const { locale } = await params;
+      const schoolType = await getSchoolType();
+
+      return (
+        <IntlayerServerProvider locale={locale} variant={schoolType}>
+          <IntlayerClientProvider locale={locale} variant={schoolType}>
+            {children}
+          </IntlayerClientProvider>
+        </IntlayerServerProvider>
+      );
+    }
+    ```
+
+  </Tab>
+  <Tab label="Vue" value="vue">
+    ```ts fileName="main.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { createApp } from "vue";
+    import { installIntlayer } from "vue-intlayer";
+    import App from "./App.vue";
+
+    const app = createApp(App);
+
+    installIntlayer(app, { locale: "en", variant: schoolType });
+
+    app.mount("#app");
+    ```
+
+  </Tab>
+  <Tab label="Svelte" value="svelte">
+    ```svelte fileName="+layout.svelte" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    <script lang="ts">
+    import { setupIntlayer } from "svelte-intlayer";
+
+    export let schoolType: string;
+
+    setupIntlayer("en", schoolType);
+    </script>
+
+    <slot />
+    ```
+
+  </Tab>
+  <Tab label="Preact" value="preact">
+    ```tsx fileName="App.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { IntlayerProvider } from "preact-intlayer";
+
+    export const App = ({ locale, schoolType }) => (
+      <IntlayerProvider locale={locale} variant={schoolType}>
+        <Hero />
+      </IntlayerProvider>
+    );
+    ```
+
+  </Tab>
+  <Tab label="Solid" value="solid">
+    ```tsx fileName="App.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { IntlayerProvider } from "solid-intlayer";
+
+    export const App = (props) => (
+      <IntlayerProvider locale={props.locale} variant={props.schoolType}>
+        <Hero />
+      </IntlayerProvider>
+    );
+    ```
+
+  </Tab>
+  <Tab label="Angular" value="angular">
+    ```typescript fileName="app.config.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { ApplicationConfig } from "@angular/core";
+    import { provideIntlayer } from "angular-intlayer";
+
+    export const appConfig: ApplicationConfig = {
+      providers: [provideIntlayer("en", true, schoolType)],
+    };
+    ```
+
+  </Tab>
+  <Tab label="Vanilla JS" value="vanilla">
+    ```javascript fileName="main.js"
+    import { installIntlayer } from "vanilla-intlayer";
+
+    installIntlayer({ locale: "en", variant: schoolType });
+    ```
+
+  </Tab>
+</Tabs>
+
+Cada lectura de diccionario bajo el proveedor se resuelve ahora con esa variante, y un selector en el punto de llamada siempre gana:
+
+```tsx
+useIntlayer("hero-banner");
+// → la variante del proveedor
+
+useIntlayer("hero-banner", { variant: "summer" });
+// → "summer" — sustituye la variante del proveedor, no la extiende
+```
+
+### Formas
+
+La prop `variant` acepta tres formas:
+
+| Forma                                                     | Significado                                 |
+| --------------------------------------------------------- | ------------------------------------------- |
+| `variant="school1"`                                       | una variante nombrada para todas las claves |
+| `variant={["school1", "default"]}`                        | una cadena de preferencia ordenada          |
+| `variant={{ "hero-banner": "school1", default: "base" }}` | una variante por clave de diccionario       |
+
+#### Cadena de preferencia
+
+Una cadena se recorre de izquierda a derecha frente a las entradas que declara cada clave, y gana la primera declarada. Cuando no hay ninguna declarada, se usa la entrada por defecto implícita, exactamente igual que con un valor único.
+
+```tsx
+<IntlayerProvider variant={["school1", "school2"]} />
+// `hero-banner` no declara una entrada `school1` pero sí declara `school2` → "school2"
+// una clave que no declara ninguna de las dos → la entrada por defecto
+```
+
+Así, `["black_friday", "summer"]` se lee como «black friday si esta clave la tiene, si no summer, si no por defecto». Las cadenas también se aceptan en el punto de llamada:
+
+```tsx
+useIntlayer("hero-banner", { variant: ["black_friday", "summer"] });
+```
+
+> Ten en cuenta que esto es la imagen especular del array aceptado por el **campo** `variant` de un archivo de contenido: allí un array _declara_ una entrada por elemento; aquí las _consume_ por orden de prioridad.
+
+#### Mapa por clave
+
+Dirígete a cada clave de diccionario por separado. La entrada reservada `default` cubre todas las claves no listadas:
+
+```tsx
+<IntlayerProvider
+  variant={{
+    "hero-banner": "school1",
+    product: ["school1", "default"],
+    default: "base",
+  }}
+/>
+```
+
+> En un proveedor, un objeto simple se lee **siempre** como el mapa por clave, nunca como una variante de objeto: ambos son estructuralmente idénticos. Para fijar una variante de objeto globalmente, anídala bajo una entrada: `variant={{ default: { id: "prod_abc" } }}`.
+
+Como las claves del mapa se comprueban contra tus claves de diccionario declaradas, una errata —o una variante de objeto escrita directamente, como `variant={{ id: "prod_abc" }}`— es un error de compilación.
+
 ## Modo de carga
 
 Las variantes de objeto suelen cargarse de forma diferida. Establezca `importMode` en el diccionario para controlarlo:

package/docs/fr/dynamic_dictionaries/variants.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-06-12
-updatedAt: 2026-06-26
+updatedAt: 2026-08-04
 title: Variantes
 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:
@@ -23,6 +23,12 @@ history:
   - 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"
+  - version: 9.1.1
+    date: 2026-07-31
+    changes: "Une variante déclare uniquement les clés qu'elle remplace ; les variantes non déclarées se rabattent sur l'entrée par défaut"
+  - version: 9.1.2
+    date: 2026-08-04
+    changes: "Les fournisseurs acceptent une prop `variant` ambiante ; les sélecteurs acceptent une chaîne de préférence ordonnée"
 author: aymericzip
 ---
 
@@ -77,6 +83,37 @@ const dictionary = {
 export default dictionary;
 ```
 
+### Variantes partielles
+
+Une variante déclare **uniquement les clés qu'elle remplace** ; le reste est hérité de l'entrée par défaut.
+
+```ts fileName="hero-banner.summer.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+import { t, type Dictionary } from "intlayer";
+
+const dictionary = {
+  key: "hero-banner",
+  variant: "summer",
+  content: {
+    headline: t({
+      en: "Build faster all summer",
+      fr: "Développez plus vite tout l'été",
+    }),
+  },
+} satisfies Dictionary;
+
+export default dictionary;
+```
+
+```tsx
+useIntlayer("hero-banner", { variant: "summer" });
+// → { headline: "Développez plus vite tout l'été", cta: "Commencer" } — `cta` hérité
+
+useIntlayer("hero-banner", { variant: "never-declared" });
+// → l'entrée par défaut
+```
+
+Ainsi, vous n'ajoutez un fichier de variante que là où la formulation diffère réellement. Une clé se résout en `null` uniquement lorsqu'elle déclare des variantes mais aucune entrée par défaut.
+
 ### Consommer des variantes nommées
 
 #### Variante par défaut
@@ -464,6 +501,176 @@ const content = useIntlayer("product", {
 const content = useIntlayer("product", { variant: { id: "prod_abc" } });
 ```
 
+## Variante ambiante
+
+Certaines dimensions de variante sont fixes pour toute une session — le locataire, le type d'établissement, le niveau d'abonnement. Elles sont résolues une seule fois, et aucun composant ne devrait avoir à les passer à la main.
+
+> N'encapsulez pas `useIntlayer` dans votre propre hook pour les injecter. L'optimisation à la compilation ne réécrit qu'un appel littéral `useIntlayer("key")` importé depuis le paquet du framework : rien derrière un wrapper n'est intégré au bundle.
+
+Déclarez plutôt la variante une seule fois sur le fournisseur, exactement comme `locale` :
+
+<Tabs group="framework">
+  <Tab label="React" value="react">
+    ```tsx fileName="App.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { IntlayerProvider } from "react-intlayer";
+
+    export const App = ({ locale, schoolType }) => (
+      <IntlayerProvider locale={locale} variant={schoolType}>
+        <Hero />
+      </IntlayerProvider>
+    );
+    ```
+
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+    ```tsx fileName="layout.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { IntlayerServerProvider } from "next-intlayer/server";
+    import { IntlayerClientProvider } from "next-intlayer";
+
+    export default async function Layout({ children, params }) {
+      const { locale } = await params;
+      const schoolType = await getSchoolType();
+
+      return (
+        <IntlayerServerProvider locale={locale} variant={schoolType}>
+          <IntlayerClientProvider locale={locale} variant={schoolType}>
+            {children}
+          </IntlayerClientProvider>
+        </IntlayerServerProvider>
+      );
+    }
+    ```
+
+  </Tab>
+  <Tab label="Vue" value="vue">
+    ```ts fileName="main.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { createApp } from "vue";
+    import { installIntlayer } from "vue-intlayer";
+    import App from "./App.vue";
+
+    const app = createApp(App);
+
+    installIntlayer(app, { locale: "en", variant: schoolType });
+
+    app.mount("#app");
+    ```
+
+  </Tab>
+  <Tab label="Svelte" value="svelte">
+    ```svelte fileName="+layout.svelte" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    <script lang="ts">
+    import { setupIntlayer } from "svelte-intlayer";
+
+    export let schoolType: string;
+
+    setupIntlayer("en", schoolType);
+    </script>
+
+    <slot />
+    ```
+
+  </Tab>
+  <Tab label="Preact" value="preact">
+    ```tsx fileName="App.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { IntlayerProvider } from "preact-intlayer";
+
+    export const App = ({ locale, schoolType }) => (
+      <IntlayerProvider locale={locale} variant={schoolType}>
+        <Hero />
+      </IntlayerProvider>
+    );
+    ```
+
+  </Tab>
+  <Tab label="Solid" value="solid">
+    ```tsx fileName="App.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { IntlayerProvider } from "solid-intlayer";
+
+    export const App = (props) => (
+      <IntlayerProvider locale={props.locale} variant={props.schoolType}>
+        <Hero />
+      </IntlayerProvider>
+    );
+    ```
+
+  </Tab>
+  <Tab label="Angular" value="angular">
+    ```typescript fileName="app.config.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { ApplicationConfig } from "@angular/core";
+    import { provideIntlayer } from "angular-intlayer";
+
+    export const appConfig: ApplicationConfig = {
+      providers: [provideIntlayer("en", true, schoolType)],
+    };
+    ```
+
+  </Tab>
+  <Tab label="Vanilla JS" value="vanilla">
+    ```javascript fileName="main.js"
+    import { installIntlayer } from "vanilla-intlayer";
+
+    installIntlayer({ locale: "en", variant: schoolType });
+    ```
+
+  </Tab>
+</Tabs>
+
+Chaque lecture de dictionnaire sous le fournisseur se résout désormais avec cette variante, et un sélecteur au point d'appel l'emporte toujours :
+
+```tsx
+useIntlayer("hero-banner");
+// → la variante du fournisseur
+
+useIntlayer("hero-banner", { variant: "summer" });
+// → "summer" — remplace la variante du fournisseur, elle ne l'étend pas
+```
+
+### Formes
+
+La prop `variant` accepte trois formes :
+
+| Forme                                                     | Signification                            |
+| --------------------------------------------------------- | ---------------------------------------- |
+| `variant="school1"`                                       | une variante nommée pour toutes les clés |
+| `variant={["school1", "default"]}`                        | une chaîne de préférence ordonnée        |
+| `variant={{ "hero-banner": "school1", default: "base" }}` | une variante par clé de dictionnaire     |
+
+#### Chaîne de préférence
+
+Une chaîne est parcourue de gauche à droite parmi les entrées déclarées par chaque clé, et la première déclarée l'emporte. Si aucune ne l'est, l'entrée par défaut implicite est utilisée — exactement comme pour une valeur unique.
+
+```tsx
+<IntlayerProvider variant={["school1", "school2"]} />
+// `hero-banner` ne déclare pas d'entrée `school1` mais déclare `school2` → "school2"
+// une clé qui ne déclare ni l'une ni l'autre → l'entrée par défaut
+```
+
+Ainsi `["black_friday", "summer"]` se lit « black friday si cette clé en a une, sinon summer, sinon par défaut ». Les chaînes sont également acceptées au point d'appel :
+
+```tsx
+useIntlayer("hero-banner", { variant: ["black_friday", "summer"] });
+```
+
+> Notez qu'il s'agit de l'image inverse du tableau accepté par le **champ** `variant` d'un fichier de contenu : là, un tableau _déclare_ une entrée par élément ; ici, il les _consomme_ par ordre de priorité.
+
+#### Table par clé
+
+Adressez chaque clé de dictionnaire séparément. L'entrée réservée `default` couvre toutes les clés non listées :
+
+```tsx
+<IntlayerProvider
+  variant={{
+    "hero-banner": "school1",
+    product: ["school1", "default"],
+    default: "base",
+  }}
+/>
+```
+
+> Sur un fournisseur, un objet simple est **toujours** lu comme la table par clé, jamais comme une variante objet — les deux sont structurellement identiques. Pour fixer une variante objet globalement, imbriquez-la sous une entrée : `variant={{ default: { id: "prod_abc" } }}`.
+
+Comme les clés de la table sont vérifiées par rapport à vos clés de dictionnaire déclarées, une faute de frappe — ou une variante objet écrite directement, telle que `variant={{ id: "prod_abc" }}` — est une erreur de compilation.
+
 ## 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 :