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

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:
@@ -17,17 +19,27 @@ slugs:
 history:
   - 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

package/docs/it/plugins/sync-json.md

@@ -108,7 +108,6 @@ const config: IntlayerConfig = {
      * Caricherà e scriverà l'output e le traduzioni nei file JSON nella directory locales
      */
     syncJSON({
-      format: "i18next",
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
       priority: 0,
       format: "i18next",

package/docs/it/releases/v9.md

@@ -1,15 +1,14 @@
 ---
 createdAt: 2026-06-14
-updatedAt: 2026-06-25
+updatedAt: 2026-06-26
 title: Nuovo Intlayer v9 - Cosa c'è di nuovo?
-description: Scopri le novità di Intlayer v9. Introduzione di package di compatibilità drop-in per le più diffuse librerie i18n e supporto per Collections, Variants e Dynamic Records.
+description: Scopri le novità di Intlayer v9. Introduzione di package di compatibilità drop-in per le più diffuse librerie i18n e supporto per Collections e Variants.
 keywords:
   - Intlayer
   - Compatibilità
   - Migrazione
   - Collections
   - Variants
-  - Dynamic Records
   - i18next
   - next-intl
   - vue-i18n
@@ -22,7 +21,7 @@ author: aymericzip
 
 # Nuovo Intlayer v9 - Cosa c'è di nuovo?
 
-Benvenuti a Intlayer v9! Questa major release segna un'enorme pietra miliare nella semplificazione del percorso di migrazione a Intlayer con i **Compat Adapter Packages** per le principali librerie i18n (`react-i18next`, `next-intl`, `vue-i18n`, ecc.) e aggiunge il supporto per strutture di contenuto ricche: **Collections**, **Variants** e **Dynamic Records**.
+Benvenuti a Intlayer v9! Questa major release segna un'enorme pietra miliare nella semplificazione del percorso di migrazione a Intlayer con i **Compat Adapter Packages** per le principali librerie i18n (`react-i18next`, `next-intl`, `vue-i18n`, ecc.) e aggiunge il supporto per strutture di contenuto ricche: **Collections** e **Variants**.
 
 ## Indice
 
@@ -41,8 +40,10 @@ Sostituendo gli import, ottieni tutti i vantaggi di Intlayer (inclusa la type sa
 - `@intlayer/i18next`
 - `@intlayer/react-i18next`
 - `@intlayer/next-intl`
+- `@intlayer/react-intl`
 - `@intlayer/next-i18next`
 - `@intlayer/vue-i18n`
+- `@intlayer/lingui`
 
 Ad esempio, è sufficiente cambiare:
 
@@ -100,7 +101,7 @@ Tutti i compat adapter ora instradano la risoluzione delle traduzioni attraverso
 
 ---
 
-## Specifica delle Funzionalità: Collections, Variants & Dynamic Records
+## Specifica delle Funzionalità: Collections & Variants
 
 Intlayer v9 si espande oltre gli oggetti chiave-valore statici, consentendo ai dizionari di dichiarare strutture di layout dinamiche che sono completamente tipizzate end-to-end.
 
@@ -144,6 +145,8 @@ const faq = useIntlayer("faq", { item: 1 }); // -> { question: string, answer: s
 
 Fornisci A/B test, header stagionali, feature flag o landing page personalizzate:
 
+#### Varianti stringa (es. test A/B)
+
 ```ts fileName="hero.content.ts"
 import { t, type Dictionary } from "intlayer";
 
@@ -167,16 +170,14 @@ export default {
 const banner = useIntlayer("hero-banner", { variant: "black_friday" });
 ```
 
-### 3. Dynamic Records
-
-Definisci dizionari le cui voci vengono caricate dinamicamente a runtime tramite ID di query:
+#### Varianti oggetto (es. Dynamic Records)
 
 ```ts fileName="product.content.ts"
 import { t, type Dictionary } from "intlayer";
 
 export default {
   key: "product-copy",
-  meta: {
+  variant: {
     id: "prod_123",
     category: "books",
   },
@@ -229,7 +230,7 @@ export default defineConfig({
 });
 ```
 
-- **Compiler**: Si attiva automaticamente quando `compiler.enabled` è impostato e un percorso `compiler.output` è configurato. Non è più necessario registrare `intlayerCompiler()` separatamente.
+- **Compiler**: Si attiva automaticamente quando `compiler.enabled` è impostato su `true` e un percorso `compiler.output` è configurato. Non è più necessario registrare `intlayerCompiler()` separatamente.
 - **Proxy**: Si attiva automaticamente in base alla nuova opzione `routing.enableProxy` (`true` per impostazione predefinita). Collega il middleware di rilevamento locale / reindirizzamento / riscrittura in sviluppo, anteprima e SSR in produzione. Non è più necessario registrare `intlayerProxy()` separatamente.
 
 ### Opzione `routing.enableProxy`
@@ -252,6 +253,27 @@ I plugin standalone `intlayerCompiler()` e `intlayerProxy()` rimangono esportati
 
 ---
 
+## Compilatore disabilitato per impostazione predefinita
+
+A partire da Intlayer v9, il **compilatore è disabilitato per impostazione predefinita** (`compiler.enabled` ora ha come valore predefinito `false`). Per abilitare l'estrazione dei tuoi file `.content.ts` in fase di build, imposta `compiler.enabled: true` nella tua configurazione:
+
+```ts fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  compiler: {
+    enabled: true, // Predefinito: false — richiesto per abilitare il compilatore dalla v9
+    output: ({ fileName }) => `./${fileName}.content.ts`,
+  },
+};
+
+export default config;
+```
+
+Quando il compilatore è disabilitato, Intlayer salta il passaggio di estrazione in fase di build e si basa sui dizionari che hai già dichiarato. Abilitalo solo quando vuoi che il plugin del bundler (`@intlayer/swc`, `@intlayer/babel` o il plugin Vite `intlayer()`) estragga il contenuto automaticamente.
+
+---
+
 ## React Native: importazioni da un unico pacchetto
 
 In un'app React Native o Expo, non è più necessario destreggiarsi tra `react-intlayer` e `react-native-intlayer`. Il pacchetto `react-native-intlayer` ora **riesporta l'intera API `react-intlayer`** (hook, utility e i sottopercorsi `/format`, `/html` e `/markdown`), e il suo `IntlayerProvider` applica automaticamente i polyfill di React Native.
@@ -278,13 +300,14 @@ npm install intlayer react-native-intlayer
 
 Se stai eseguendo l'aggiornamento da v8, nota che la v9 non include breaking changes. Ma ecco le modifiche chiave:
 
+- **Compilatore disabilitato per impostazione predefinita**: `compiler.enabled` ora ha come valore predefinito `false`. Se dipendi dall'estrazione dei tuoi file `.content.ts` in fase di build, imposta `compiler.enabled: true` nel tuo `intlayer.config.ts`.
 - **Locales & Dialects**: Se utilizzi dipendenze i18n esterne, aggiungi i rispettivi compat adapter plugin nella tua configurazione o setup del bundler per riscrivere automaticamente gli import.
-- **Custom Selectors**: Quando chiami `useIntlayer`, il secondo parametro è ora riservato a un oggetto di opzioni contenente `{ locale, item, variant, id }`. Se in precedenza passavi direttamente una stringa locale, puoi ancora farlo, ma l'utilizzo dell'oggetto di opzioni è consigliato per selezioni avanzate.
+- **Custom Selectors**: Quando chiami `useIntlayer`, il secondo parametro è ora riservato a un oggetto di opzioni contenente `{ locale, item, variant }`. Se in precedenza passavi direttamente una stringa locale, puoi ancora farlo, ma l'utilizzo dell'oggetto di opzioni è consigliato per selezioni avanzate.
 
 ---
 
 ## Link utili
 
 - [Guida ai Compat Adapter Packages](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/compat/index.md)
-- [Dizionari Dinamici - Collections, Variants & Dynamic Records](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dynamic_dictionaries/index.md)
+- [Dizionari Dinamici - Collections & Variants](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dynamic_dictionaries/index.md)
 - [Riferimento alla Configurazione](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/configuration.md)

package/docs/ja/dynamic_dictionaries/index.md

@@ -1,13 +1,12 @@
 ---
 createdAt: 2026-06-12
-updatedAt: 2026-06-12
-title: 動的ディクショナリ
-description: 柔軟でランタイム駆動のi18nコンテンツを構築するための、Intlayerの3つの動的ディクショナリ機能 — コレクション、バリアント、動的レコード — の概要。
+updatedAt: 2026-06-26
+title: 動的辞書
+description: Intlayer の動的辞書機能（コレクションとバリアント）の概要。柔軟でランタイム駆動の i18n コンテンツを構築するために。
 keywords:
-  - 動的ディクショナリ
+  - 動的辞書
   - コレクション
   - バリアント
-  - 動的レコード
   - Intlayer
   - 国際化
 slugs:
@@ -17,32 +16,39 @@ slugs:
 history:
   - version: 9.0.0
     date: 2026-06-12
-    changes: "動的ディクショナリ機能のリリース"
+    changes: "動的辞書機能のリリース"
+  - version: 9.1.0
+    date: 2026-06-26
+    changes: "動的レコードをバリアントに統合 — `variant` が文字列またはオブジェクトを受け取るようになりました"
 author: aymericzip
 ---
 
-# 動的ディクショナリ
+# 動的辞書
 
-Intlayerは、キーごとに単一の静的ディクショナリを定義するだけでなく、それを超えたコンテンツを表現するための3つのメカニズムをサポートしています。それぞれ、コンテンツファイル内の**最上位メタデータフィールド**を介して宣言され、ラッパー関数は不要です。
+Intlayer は、キーごとの単一の静的辞書を超えるコンテンツを表現するための 2 つのメカニズムをサポートします。それぞれはコンテンツファイル内の**トップレベルのメタデータフィールド**で宣言され、ラッパー関数は不要です。
 
-| 機能                                                                                                                  | メタデータフィールド | `useIntlayer` でのセレクター |
-| --------------------------------------------------------------------------------------------------------------------- | -------------------- | ---------------------------- |
-| [コレクション](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/dynamic_dictionaries/collections.md)     | `item: N`            | `{ item: N }`                |
-| [バリアント](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/dynamic_dictionaries/variants.md)          | `variant: "name"`    | `{ variant: "name" }`        |
-| [動的レコード](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/dynamic_dictionaries/dynamic_content.md) | `meta: { id, … }`    | `{ id, … }`                  |
+| 機能                                                                                                              | メタデータフィールド                        | `useIntlayer` のセレクター                          |
+| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | --------------------------------------------------- |
+| [コレクション](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/dynamic_dictionaries/collections.md) | `item: N`                                   | `{ item: N }`                                       |
+| [バリアント](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/dynamic_dictionaries/variants.md)      | `variant: "name"` _または_ `variant: { … }` | `{ variant: "name" }` _または_ `{ variant: { … } }` |
 
-3つのメカニズムすべてがロケール引数と連携し、`importMode` を介した選択的 / 遅延読み込みをサポートしています。
+いずれも locale 引数と組み合わせられ、`importMode` による選択的 / 遅延読み込みをサポートします。
 
-## 使い分け
+## どちらをいつ使うか
 
-- **コレクション** — 別ファイルで管理されるアイテムの順序付きリスト（FAQ項目、ブログ記事、商品など）。
-- **バリアント** — A/Bテスト、季節限定のバナー、または機能フラグ（feature flags）用の、名前付きコンテンツ代替案。
-- **動的レコード** — 不透明なIDを使用してランタイムに取得されるコンテンツ（CMSレコード、ユーザー固有のコピーなど）。
+- **コレクション** — 別々のファイルで管理される順序付きの項目リスト（FAQ 項目、ブログ記事、商品）。
+- **バリアント** — 名前付きまたは構造化されたコンテンツの代替:
+  - A/B テスト、季節バナー、フィーチャーフラグ向けの**文字列**バリアント。
+  - CMS レコード、ユーザー固有のコピー、またはフィールドの集合でアドレス指定される任意のコンテンツ向けの**オブジェクト**バリアント（旧「動的レコード」）。
 
-## セレクターの競合解決
+> 以前のバージョンでは、レコードキー付きコンテンツ用に別個の `meta` フィールドを公開していました。これは `variant` に統合されました。`meta` を使う代わりに `variant` に**オブジェクト**を渡してください。
 
-1つのディクショナリに複数のセレクターが存在する場合、解決の優先順位は次のようになります：
+## セレクターの曖昧性解消
+
+キーは両方の次元を同時に宣言できます（例: 各項目にバリアントを持つコレクション）。これらは次の順序で解決されます:
 
 ```
-variant → meta → item
+variant → item
 ```
+
+したがって、variant × item キーでの `{ variant: "promo" }` はすべての promo 項目を配列として返し、`{ item: 2 }` を追加すると単一のエントリに絞り込まれます。