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

package/docs/it/dictionary/translation.md

@@ -85,7 +85,10 @@ export default config;
 
 ## Utilizzo delle Traduzioni nei Componenti React
 
-Con `react-intlayer`, puoi utilizzare le traduzioni nei componenti React. Ecco un esempio:
+<Tabs group="framework">
+  <Tab label="React" value="react">
+
+With `react-intlayer`, you can use translations in React components. Here's an example:
 
 ```jsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
 import type { FC } from "react";
@@ -104,65 +107,155 @@ const MyComponent: FC = () => {
 export default MyComponent;
 ```
 
-Questo componente recupera la traduzione corrispondente in base alla locale corrente impostata nella tua applicazione.
+This component fetches the corresponding translation based on the current locale set in your application.
 
-## Oggetti di Contenuto Personalizzati
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
 
-`intlayer` supporta oggetti di contenuto personalizzati per la traduzione, permettendoti di definire strutture più complesse garantendo al contempo la sicurezza dei tipi. Ecco un esempio con un oggetto personalizzato:
+With `next-intlayer`, you can use translations in React Server Components or Client Components. Here's an example in a Client Component:
 
-```typescript fileName="**/*.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
-import { t, type Dictionary } from "intlayer";
+```tsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
+"use client";
 
-interface ICustomContent {
-  title: string;
-  content: string;
-}
+import type { FC } from "react";
+import { useIntlayer } from "next-intlayer";
 
-const customContent = {
-  key: "custom_content",
-  content: {
-    profileText: t<ICustomContent>({
-      en: {
-        title: "Page Title",
-        content: "Page Content",
-      },
-      fr: {
-        title: "Titre de la Page",
-        content: "Contenu de la Page",
-      },
-      es: {
-        title: "Título de la Página",
-        content: "Contenido de la Página",
-      },
-    }),
-  },
-} satisfies Dictionary;
+const MyComponent: FC = () => {
+  const content = useIntlayer("multi_lang");
 
-export default customContent;
+  return (
+    <div>
+      <p>{content.welcomeMessage}</p>
+    </div>
+  );
+};
+
+export default MyComponent;
 ```
 
-```json fileName="**/*.content.json" contentDeclarationFormat="json"
-{
-  "$schema": "https://intlayer.org/schema.json",
-  "key": "custom_content",
-  "content": {
-    "profileText": {
-      "nodeType": "translation",
-      "translation": {
-        "en": {
-          "title": "Page Title",
-          "content": "Contenuto della Pagina"
-        },
-        "fr": {
-          "title": "Titre de la Page",
-          "content": "Contenu de la Page"
-        },
-        "es": {
-          "title": "Título de la Página",
-          "content": "Contenido de la Página"
-        }
-      }
-    }
-  }
+  </Tab>
+  <Tab label="Vue" value="vue">
+
+With `vue-intlayer`, you can use translations in Vue components. Here's an example:
+
+```vue fileName="**/*.vue"
+<script setup lang="ts">
+import { useIntlayer } from "vue-intlayer";
+
+const content = useIntlayer("multi_lang");
+</script>
+
+<template>
+  <div>
+    <p>{{ content.welcomeMessage }}</p>
+  </div>
+</template>
+```
+
+  </Tab>
+  <Tab label="Svelte" value="svelte">
+
+With `svelte-intlayer`, you can use translations in Svelte components. The hook returns a Svelte store. Here's an example:
+
+```svelte fileName="**/*.svelte"
+<script lang="ts">
+import { useIntlayer } from "svelte-intlayer";
+
+const content = useIntlayer("multi_lang");
+</script>
+
+<div>
+  <p>{$content.welcomeMessage}</p>
+</div>
+```
+
+  </Tab>
+  <Tab label="Preact" value="preact">
+
+With `preact-intlayer`, you can use translations in Preact components. Here's an example:
+
+```tsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
+import type { FC } from "preact";
+import { useIntlayer } from "preact-intlayer";
+
+const MyComponent: FC = () => {
+  const content = useIntlayer("multi_lang");
+
+  return (
+    <div>
+      <p>{content.welcomeMessage}</p>
+    </div>
+  );
+};
+
+export default MyComponent;
+```
+
+  </Tab>
+  <Tab label="Solid" value="solid">
+
+With `solid-intlayer`, you can use translations in SolidJS components. Here's an example:
+
+```tsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
+import type { Component } from "solid-js";
+import { useIntlayer } from "solid-intlayer";
+
+const MyComponent: Component = () => {
+  const content = useIntlayer("multi_lang");
+
+  return (
+    <div>
+      <p>{content.welcomeMessage}</p>
+    </div>
+  );
+};
+
+export default MyComponent;
+```
+
+  </Tab>
+  <Tab label="Angular" value="angular">
+
+With `angular-intlayer`, you can use translations in Angular components. Here's an example:
+
+```typescript fileName="app.component.ts" codeFormat="typescript"
+import { Component } from "@angular/core";
+import { useIntlayer } from "angular-intlayer";
+
+@Component({
+  selector: "app-my-component",
+  template: `
+    <div>
+      <p>{{ content().welcomeMessage }}</p>
+    </div>
+  `,
+})
+export class MyComponent {
+  content = useIntlayer("multi_lang");
 }
 ```
+
+  </Tab>
+  <Tab label="Vanilla JS" value="vanilla">
+
+With `vanilla-intlayer`, you can use translations by subscribing to content changes. Here's an example:
+
+```typescript fileName="**/*.ts" codeFormat={["typescript", "esm"]}
+import { installIntlayer, useIntlayer } from "vanilla-intlayer";
+
+installIntlayer();
+
+const content = useIntlayer("multi_lang").onChange((newContent) => {
+  document.getElementById("welcome-message")!.textContent = String(
+    newContent.welcomeMessage
+  );
+});
+
+// Initial render
+document.getElementById("welcome-message")!.textContent = String(
+  content.welcomeMessage
+);
+```
+
+  </Tab>
+</Tabs>

package/docs/it/dynamic_dictionaries/collections.md

@@ -14,7 +14,7 @@ slugs:
   - concept
   - collections
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-12
     changes: "Rilascio della funzionalità delle collezioni di dizionari"
 author: aymericzip

package/docs/it/dynamic_dictionaries/index.md

@@ -1,13 +1,12 @@
 ---
 createdAt: 2026-06-12
-updatedAt: 2026-06-12
-title: Dizionari Dinamici
-description: Panoramica delle tre funzionalità di dizionario dinamico di Intlayer — collezioni, varianti e record dinamici — per la creazione di contenuti i18n flessibili e guidati dal runtime.
+updatedAt: 2026-06-26
+title: Dizionari dinamici
+description: Panoramica delle funzionalità dei dizionari dinamici di Intlayer — collezioni e varianti — per creare contenuti i18n flessibili e guidati a runtime.
 keywords:
-  - Dizionari Dinamici
+  - Dizionari dinamici
   - Collezioni
   - Varianti
-  - Record Dinamici
   - Intlayer
   - Internazionalizzazione
 slugs:
@@ -15,34 +14,41 @@ slugs:
   - concept
   - dynamic-dictionaries
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-12
     changes: "Rilascio della funzionalità dei dizionari dinamici"
+  - version: 9.1.0
+    date: 2026-06-26
+    changes: "Unione dei record dinamici nelle varianti — `variant` ora accetta una stringa o un oggetto"
 author: aymericzip
 ---
 
-# Dizionari Dinamici
+# Dizionari dinamici
 
-Intlayer supporta tre meccanismi per esprimere contenuti che vanno oltre un singolo dizionario statico per chiave. Ognuno viene dichiarato tramite un **campo di metadati di livello superiore** nel file di contenuto; non è necessaria alcuna funzione wrapper.
+Intlayer supporta due meccanismi per esprimere contenuti che vanno oltre un singolo dizionario statico per chiave. Ciascuno è dichiarato tramite un **campo di metadati di primo livello** nel file di contenuto; non è necessaria alcuna funzione wrapper.
 
-| Funzionalità                                                                                                             | Campo metadati    | Selettore in `useIntlayer` |
-| ------------------------------------------------------------------------------------------------------------------------ | ----------------- | -------------------------- |
-| [Collezioni](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dynamic_dictionaries/collections.md)          | `item: N`         | `{ item: N }`              |
-| [Varianti](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dynamic_dictionaries/variants.md)               | `variant: "name"` | `{ variant: "name" }`      |
-| [Record Dinamici](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dynamic_dictionaries/dynamic_content.md) | `meta: { id, … }` | `{ id, … }`                |
+| Funzionalità                                                                                                    | Campo di metadati                      | Selettore in `useIntlayer`                     |
+| --------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ---------------------------------------------- |
+| [Collezioni](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dynamic_dictionaries/collections.md) | `item: N`                              | `{ item: N }`                                  |
+| [Varianti](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dynamic_dictionaries/variants.md)      | `variant: "name"` _o_ `variant: { … }` | `{ variant: "name" }` _o_ `{ variant: { … } }` |
 
-Tutti e tre si compongono con l'argomento della locale e supportano il caricamento selettivo o lazy tramite `importMode`.
+Entrambi si combinano con l'argomento locale e supportano il caricamento selettivo / differito tramite `importMode`.
 
-## Quando usare quale
+## Quando usare cosa
 
-- **Collezioni** — elenco ordinato di elementi gestiti in file separati (domande frequenti, post di blog, prodotti).
-- **Variantes** — alternative di contenuto denominate per test A/B, banner stagionali o feature flag.
-- **Record dinamici** — contenuto recuperato a runtime tramite un ID opaco (record del CMS, testi specifici dell'utente).
+- **Collezioni** — elenco ordinato di elementi gestiti in file separati (voci di FAQ, articoli di blog, prodotti).
+- **Varianti** — alternative di contenuto con nome o strutturate:
+  - una variante **stringa** per test A/B, banner stagionali o feature flag;
+  - una variante **oggetto** per record di CMS, contenuti specifici per utente o qualsiasi contenuto indirizzato da un insieme di campi (i precedenti «record dinamici»).
 
-## Risoluzione dei conflitti del selettore
+> Le versioni precedenti esponevano un campo `meta` separato per i contenuti indicizzati per record. È stato unito in `variant`: passa un **oggetto** a `variant` invece di usare `meta`.
 
-Quando sono presenti più selettori in un dizionario, l'ordine di risoluzione è:
+## Disambiguazione del selettore
+
+Una chiave può dichiarare entrambe le dimensioni contemporaneamente (ad es. una collezione i cui elementi hanno ciascuno una variante). Vengono risolte nell'ordine:
 
 ```
-variant → meta → item
+variant → item
 ```
+
+Quindi `{ variant: "promo" }` su una chiave variante × item restituisce tutti gli elementi promo come array, e aggiungere `{ item: 2 }` lo restringe a una singola voce.

package/docs/it/dynamic_dictionaries/variants.md

@@ -1,13 +1,15 @@
 ---
 createdAt: 2026-06-12
-updatedAt: 2026-06-12
+updatedAt: 2026-06-26
 title: Varianti
-description: Utilizza il campo dei metadati variant nei file di contenuto di Intlayer per dichiarare alternative di contenuto denominate (test A/B, banner stagionali, testi sotto feature flag) e passare da una all'altra a runtime senza modifiche al codice.
+description: Usa il campo di metadati variant nei file di contenuto Intlayer per dichiarare alternative di contenuto con nome o strutturate — test A/B, banner stagionali, testo con feature flag, record di CMS, contenuti specifici per utente — e passare dall'una all'altra a runtime senza modifiche al codice.
 keywords:
   - Varianti
   - Test A/B
   - Feature Flag
-  - Contenuto Dinamico
+  - Contenuto dinamico
+  - Record dinamici
+  - CMS
   - Intlayer
   - Internazionalizzazione
 slugs:
@@ -15,19 +17,29 @@ slugs:
   - concept
   - variants
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-12
-    changes: "Rilascio della funzionalità delle varianti di dizionari"
+    changes: "Rilascio della funzionalità delle varianti"
+  - version: 9.1.0
+    date: 2026-06-26
+    changes: "`variant` ora accetta una stringa o un oggetto — i precedenti `meta` / record dinamici si dichiarano come varianti oggetto"
 author: aymericzip
 ---
 
 # Varianti
 
-Una **variante** (Variant) è un insieme di file di contenuto che condividono la stessa chiave di dizionario (`key`) ma ognuno porta un nome di variante (`variant`) diverso. Intlayer serve il file appropriato in base al selettore passato a `useIntlayer`.
+Una **variante** è un insieme di file di contenuto che condividono la stessa chiave del dizionario (`key`) ma portano ciascuno un valore `variant` diverso. Intlayer serve il file appropriato in base al selettore passato a `useIntlayer`.
 
-## Dichiarare le varianti
+Il valore di `variant` può assumere **due forme**:
 
-Ogni file rappresenta un'alternativa denominata. Omettere `variant` (o impostarlo su `"default"`) lo contrassegna come variante di fallback (predefinita).
+- **Una stringa** — una singola alternativa con nome (test A/B, banner stagionali, feature flag).
+- **Un oggetto** — un discriminatore strutturato indirizzato da un insieme di campi (record di CMS, contenuti specifici per utente, qualsiasi contenuto con chiave un ID opaco). L'intero oggetto è l'identità: il selettore deve fornire un oggetto **uguale** per risolvere la voce.
+
+> La forma a oggetto sostituisce il precedente campo `meta`. Ovunque scrivessi `meta: { id, … }`, scrivi `variant: { id, … }` e selezionala con `{ variant: { id, … } }`.
+
+## Varianti con nome (stringa)
+
+Ogni file rappresenta un'alternativa con nome. Omettere `variant` (o impostarlo su `"default"`) la contrassegna come fallback.
 
 ```ts fileName="hero-banner.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
 import { t, type Dictionary } from "intlayer";
@@ -65,9 +77,9 @@ const dictionary = {
 export default dictionary;
 ```
 
-## Consumare le varianti
+### Consumare varianti con nome
 
-### Variante predefinita
+#### Variante predefinita
 
 <Tabs group="framework">
   <Tab label="React" value="react">
@@ -209,7 +221,7 @@ export default dictionary;
   </Tab>
 </Tabs>
 
-### Variante denominata
+#### Variante con nome
 
 ```tsx
 const { headline, cta } = useIntlayer("hero-banner", {
@@ -217,18 +229,264 @@ const { headline, cta } = useIntlayer("hero-banner", {
 });
 ```
 
-### Variante denominata con locale esplicita
+#### Variante con nome con locale esplicito
 
 ```tsx
 const content = useIntlayer("hero-banner", {
   variant: "black_friday",
-  locale: "it",
+  locale: "fr",
 });
 ```
 
+## Varianti oggetto (strutturate)
+
+Una variante oggetto indirizza il contenuto tramite un insieme arbitrario di coppie chiave-valore dichiarate nel campo `variant` — rendendo possibile modellare record di CMS, contenuti specifici per utente o qualsiasi contenuto la cui chiave è un ID opaco. L'**intero oggetto** è l'identità: il selettore deve fornire un oggetto uguale affinché la voce venga risolta.
+
+```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;
+```
+
+### Consumare varianti oggetto
+
+Passa l'oggetto corrispondente a `variant`. Ogni campo dichiarato nel dizionario deve essere fornito e uguale; altrimenti il risultato è `null`. L'ordine dei campi non ha importanza.
+
+<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>
+
+#### Con locale esplicito
+
+```tsx
+const content = useIntlayer("product", {
+  variant: { id: "prod_abc", userId: "user_123" },
+  locale: "fr",
+});
+```
+
+#### Campo mancante — nessuna corrispondenza
+
+```ts
+// Restituisce null: manca `userId`, quindi l'oggetto non corrisponde alla variante dichiarata
+const content = useIntlayer("product", { variant: { id: "prod_abc" } });
+```
+
+## Modalità di caricamento
+
+Le varianti oggetto sono spesso caricate in modo differito. Imposta `importMode` sul dizionario per controllarlo:
+
+```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;
+```
+
+Vedi [ottimizzazione del bundle](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/bundle_optimization.md) per i dettagli sulle modalità `static`, `dynamic` e `fetch`.
+
 ## Casi d'uso tipici
 
-- Test A/B guidati da una chiave di esperimento
+- Test A/B di testo guidati da una chiave di esperimento
 - Banner stagionali o promozionali
-- Messaggi condizionati da feature flag
-- Campagne di marketing specifiche per area geografica
+- Messaggistica con feature flag
+- Campagne di marketing specifiche per locale
+- Testo di marketing per prodotto gestito in un CMS
+- Contenuti specifici per utente o account
+- Qualsiasi contenuto indicizzato da un ID opaco a runtime