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

package/docs/pl/dynamic_dictionaries/variants.md

@@ -1,15 +1,17 @@
 ---
 createdAt: 2026-06-12
-updatedAt: 2026-06-12
+updatedAt: 2026-06-26
 title: Warianty
-description: Użyj pola metadanych variant w plikach zawartości Intlayer, aby deklarować nazwane alternatywne wersje treści (testy A/B, banery sezonowe, treści z flagami funkcji) i przełączać się między nimi w czasie wykonywania bez modyfikacji kodu.
+description: Użyj pola metadanych variant w plikach treści Intlayer, aby zadeklarować nazwane lub strukturalne alternatywy treści — testy A/B, banery sezonowe, teksty z feature flag, rekordy CMS, treść zależną od użytkownika — i przełączać się między nimi w czasie wykonywania bez zmian w kodzie.
 keywords:
   - Warianty
   - Testy A/B
-  - Flagi Funkcji
-  - Zawartość Dynamiczna
+  - Feature flagi
+  - Treść dynamiczna
+  - Rekordy dynamiczne
+  - CMS
   - Intlayer
-  - Umiędzynarodowienie
+  - Internacjonalizacja
 slugs:
   - doc
   - concept
@@ -17,17 +19,27 @@ slugs:
 history:
   - version: 9.0.0
     date: 2026-06-12
-    changes: "Wydanie funkcji wariantów słowników"
+    changes: "Wydanie funkcji wariantów"
+  - version: 9.1.0
+    date: 2026-06-26
+    changes: "`variant` przyjmuje teraz ciąg znaków lub obiekt — dawne `meta` / rekordy dynamiczne deklaruje się jako warianty obiektowe"
 author: aymericzip
 ---
 
 # Warianty
 
-**Wariant** (Variant) to zestaw plików zawartości, które współdzielą ten sam klucz słownika (`key`), ale każdy ma inną nazwę wariantu (`variant`). Intlayer serwuje odpowiedni plik na podstawie selektora przekazanego do `useIntlayer`.
+**Wariant** to zestaw plików treści, które dzielą ten sam klucz słownika (`key`), lecz każdy ma inną wartość `variant`. Intlayer udostępnia odpowiedni plik na podstawie selektora przekazanego do `useIntlayer`.
 
-## Deklarowanie wariantów
+Wartość `variant` może przyjmować **dwie formy**:
 
-Każdy plik reprezentuje jedną nazwaną alternatywę. Pominięcie klucza `variant` (lub ustawienie go na `"default"`) oznacza dany plik jako wariant domyślny (fallback).
+- **Ciąg znaków** — pojedyncza nazwana alternatywa (testy A/B, banery sezonowe, feature flagi).
+- **Obiekt** — strukturalny dyskryminator adresowany zestawem pól (rekordy CMS, treść zależna od użytkownika, dowolna treść z nieprzezroczystym ID jako kluczem). Tożsamością jest cały obiekt: selektor musi dostarczyć **równy** obiekt, aby rozwiązać wpis.
+
+> Forma obiektowa zastępuje dawne pole `meta`. Wszędzie, gdzie wcześniej pisałeś `meta: { id, … }`, napisz `variant: { id, … }` i wybierz ją przez `{ variant: { id, … } }`.
+
+## Warianty nazwane (tekstowe)
+
+Każdy plik reprezentuje jedną nazwaną alternatywę. Pominięcie `variant` (lub ustawienie na `"default"`) oznacza go jako domyślny.
 
 ```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;
 ```
 
-## Używanie wariantów
+### Korzystanie z wariantów nazwanych
 
-### Wariant domyślny
+#### Wariant domyślny
 
 <Tabs group="framework">
   <Tab label="React" value="react">
@@ -209,7 +221,7 @@ export default dictionary;
   </Tab>
 </Tabs>
 
-### Nazwany wariant
+#### Wariant nazwany
 
 ```tsx
 const { headline, cta } = useIntlayer("hero-banner", {
@@ -217,18 +229,264 @@ const { headline, cta } = useIntlayer("hero-banner", {
 });
 ```
 
-### Nazwany wariant z jawnym wskazaniem lokalizacji
+#### Wariant nazwany z jawnym locale
 
 ```tsx
 const content = useIntlayer("hero-banner", {
   variant: "black_friday",
-  locale: "pl",
+  locale: "fr",
 });
 ```
 
+## Warianty obiektowe (strukturalne)
+
+Wariant obiektowy adresuje treść dowolnym zestawem par klucz-wartość zadeklarowanych w polu `variant` — co umożliwia modelowanie rekordów CMS, treści zależnej od użytkownika lub dowolnej treści z nieprzezroczystym ID jako kluczem. Tożsamością jest **cały obiekt**: selektor musi dostarczyć równy obiekt, aby wpis został rozwiązany.
+
+```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;
+```
+
+### Korzystanie z wariantów obiektowych
+
+Przekaż pasujący obiekt do `variant`. Każde pole zadeklarowane w słowniku musi zostać podane i być równe; w przeciwnym razie wynik to `null`. Kolejność pól nie ma znaczenia.
+
+<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>
+
+#### Z jawnym locale
+
+```tsx
+const content = useIntlayer("product", {
+  variant: { id: "prod_abc", userId: "user_123" },
+  locale: "fr",
+});
+```
+
+#### Brakujące pole — brak dopasowania
+
+```ts
+// Zwraca null: brakuje `userId`, więc obiekt nie pasuje do zadeklarowanego wariantu
+const content = useIntlayer("product", { variant: { id: "prod_abc" } });
+```
+
+## Tryb ładowania
+
+Warianty obiektowe są często ładowane leniwie. Ustaw `importMode` w słowniku, aby to kontrolować:
+
+```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;
+```
+
+Zobacz [optymalizację bundla](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/bundle_optimization.md), aby poznać szczegóły trybów `static`, `dynamic` i `fetch`.
+
 ## Typowe przypadki użycia
 
-- Testy A/B kopii sterowane przez klucz eksperymentu
+- Testy A/B tekstu sterowane kluczem eksperymentu
 - Banery sezonowe lub promocyjne
-- Komunikaty powiązane z flagami funkcji (feature flags)
-- Lokalne kampanie marketingowe specyficzne dla danego obszaru
+- Komunikaty z feature flag
+- Kampanie marketingowe specyficzne dla locale
+- Teksty marketingowe per produkt zarządzane w CMS
+- Treść zależna od użytkownika lub konta
+- Dowolna treść adresowana nieprzezroczystym ID w czasie wykonywania

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

@@ -105,7 +105,6 @@ const config: IntlayerConfig = {
      * Will load, and write the output and translations back to the JSON files in the locales directory
      */
     syncJSON({
-      format: "i18next",
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
       priority: 0,
       format: "i18next",

package/docs/pl/releases/v9.md

@@ -1,15 +1,14 @@
 ---
 createdAt: 2026-06-14
-updatedAt: 2026-06-25
+updatedAt: 2026-06-26
 title: Nowy Intlayer v9 - Co nowego?
-description: Odkryj nowości w Intlayer v9. Przedstawiamy pakiety kompatybilności typu drop-in dla popularnych bibliotek i18n oraz wsparcie dla Kolekcji (Collections), Wariantów (Variants) i Dynamicznych Rekordów (Dynamic Records).
+description: Odkryj nowości w Intlayer v9. Przedstawiamy pakiety kompatybilności typu drop-in dla popularnych bibliotek i18n oraz wsparcie dla Kolekcji (Collections) i Wariantów (Variants).
 keywords:
   - Intlayer
   - Kompatybilność
   - Migracja
   - Kolekcje
   - Warianty
-  - Dynamiczne Rekordy
   - i18next
   - next-intl
   - vue-i18n
@@ -22,7 +21,7 @@ author: aymericzip
 
 # Nowy Intlayer v9 - Co nowego?
 
-Witaj w Intlayer v9! To główne wydanie (major release) stanowi ogromny krok milowy w upraszczaniu ścieżki migracji do Intlayer dzięki **pakietom kompatybilności (Compat Adapter Packages)** dla najpopularniejszych bibliotek i18n (takich jak `react-i18next`, `next-intl`, `vue-i18n` itp.) oraz wprowadza wsparcie dla bogatych struktur treści: **Kolekcji (Collections)**, **Wariantów (Variants)** i **Dynamicznych Rekordów (Dynamic Records)**.
+Witaj w Intlayer v9! To główne wydanie (major release) stanowi ogromny krok milowy w upraszczaniu ścieżki migracji do Intlayer dzięki **pakietom kompatybilności (Compat Adapter Packages)** dla najpopularniejszych bibliotek i18n (takich jak `react-i18next`, `next-intl`, `vue-i18n` itp.) oraz wprowadza wsparcie dla bogatych struktur treści: **Kolekcji (Collections)** i **Wariantów (Variants)**.
 
 ## Spis treści
 
@@ -41,8 +40,10 @@ Zastępując importy, zyskujesz wszystkie zalety Intlayer (w tym bezpieczeństwo
 - `@intlayer/i18next`
 - `@intlayer/react-i18next`
 - `@intlayer/next-intl`
+- `@intlayer/react-intl`
 - `@intlayer/next-i18next`
 - `@intlayer/vue-i18n`
+- `@intlayer/lingui`
 
 Na przykład, po prostu zmień:
 
@@ -100,7 +101,7 @@ Wszystkie adaptery kompatybilności kierują teraz proces rozwiązywania tłumac
 
 ---
 
-## Specyfikacja funkcji: Kolekcje, Warianty i Dynamiczne Rekordy
+## Specyfikacja funkcji: Kolekcje i Warianty
 
 Intlayer v9 wykracza poza statyczne obiekty klucz-wartość, umożliwiając słownikom deklarowanie dynamicznych struktur układu, które są w pełni typowane od początku do końca (end-to-end).
 
@@ -144,6 +145,8 @@ const faq = useIntlayer("faq", { item: 1 }); // -> { question: string, answer: s
 
 Dostarczaj testy A/B, nagłówki sezonowe, flagi funkcji (feature flags) lub niestandardowe strony docelowe (landing pages):
 
+#### Warianty tekstowe (np. testy 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. Dynamiczne Rekordy (Dynamic Records)
-
-Definiuj słowniki, których wpisy są ładowane dynamicznie w czasie działania aplikacji (runtime) za pomocą identyfikatorów zapytań (query IDs):
+#### Warianty obiektowe (np. 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**: Aktywuje się automatycznie, gdy `compiler.enabled` jest ustawione i skonfigurowana jest ścieżka `compiler.output`. Nie musisz już rejestrować `intlayerCompiler()` osobno.
+- **Compiler**: Aktywuje się automatycznie, gdy `compiler.enabled` jest ustawione na `true` i skonfigurowana jest ścieżka `compiler.output`. Nie musisz już rejestrować `intlayerCompiler()` osobno.
 - **Proxy**: Aktywuje się automatycznie w oparciu o nową opcję `routing.enableProxy` (domyślnie `true`). Podłącza middleware do wykrywania locale'ów / przekierowywania / przepisywania w developmencie, preview i produkcyjnym SSR. Nie musisz już rejestrować `intlayerProxy()` osobno.
 
 ### Opcja `routing.enableProxy`
@@ -252,6 +253,27 @@ Autonomiczne pluginy `intlayerCompiler()` i `intlayerProxy()` pozostają eksport
 
 ---
 
+## Kompilator domyślnie wyłączony
+
+Od Intlayer v9 **kompilator jest domyślnie wyłączony** (`compiler.enabled` ma teraz domyślnie wartość `false`). Aby włączyć ekstrakcję plików `.content.ts` w czasie budowania, ustaw `compiler.enabled: true` w swojej konfiguracji:
+
+```ts fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  compiler: {
+    enabled: true, // Domyślnie: false — wymagane do włączenia kompilatora od wersji v9
+    output: ({ fileName }) => `./${fileName}.content.ts`,
+  },
+};
+
+export default config;
+```
+
+Gdy kompilator jest wyłączony, Intlayer pomija krok ekstrakcji w czasie budowania i opiera się na już zadeklarowanych słownikach. Włącz go tylko wtedy, gdy chcesz, aby plugin bundlera (`@intlayer/swc`, `@intlayer/babel` lub plugin Vite `intlayer()`) automatycznie wyodrębniał zawartość.
+
+---
+
 ## React Native: importy z jednego pakietu
 
 W aplikacji React Native lub Expo nie musisz już żonglować pakietami `react-intlayer` i `react-native-intlayer`. Pakiet `react-native-intlayer` teraz **ponownie eksportuje pełne API `react-intlayer`** (hooki, narzędzia oraz podścieżki `/format`, `/html` i `/markdown`), a jego `IntlayerProvider` automatycznie stosuje polyfille React Native.
@@ -278,13 +300,14 @@ npm install intlayer react-native-intlayer
 
 Jeśli aktualizujesz aplikację z wersji v8, pamiętaj, że wersja v9 nie zawiera zmian wprowadzających niekompatybilność wsteczną (breaking changes). Oto jednak kluczowe zmiany:
 
+- **Kompilator domyślnie wyłączony**: `compiler.enabled` ma teraz domyślnie wartość `false`. Jeśli polegasz na ekstrakcji plików `.content.ts` w czasie budowania, ustaw `compiler.enabled: true` w swoim `intlayer.config.ts`.
 - **Języki i dialekty (Locales & Dialects)**: Jeśli używasz zewnętrznych zależności i18n, dodaj odpowiednie pluginy adapterów kompatybilności w swojej konfiguracji lub konfiguracji bundlera, aby automatycznie przepisywać importy.
-- **Niestandardowe selektory (Custom Selectors)**: Podczas wywoływania `useIntlayer`, drugi parametr jest teraz zarezerwowany dla obiektu opcji zawierającego `{ locale, item, variant, id }`. Jeśli wcześniej przekazywałeś bezpośrednio ciąg znaków języka (locale string), nadal możesz to robić, jednak zaleca się używanie obiektu opcji przy bardziej zaawansowanych wyborach.
+- **Niestandardowe selektory (Custom Selectors)**: Podczas wywoływania `useIntlayer`, drugi parametr jest teraz zarezerwowany dla obiektu opcji zawierającego `{ locale, item, variant }`. Jeśli wcześniej przekazywałeś bezpośrednio ciąg znaków języka (locale string), nadal możesz to robić, jednak zaleca się używanie obiektu opcji przy bardziej zaawansowanych wyborach.
 
 ---
 
 ## Przydatne linki
 
 - [Przewodnik po pakietach kompatybilności (Compat Adapter Packages)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/compat/index.md)
-- [Dynamiczne słowniki - Kolekcje, Warianty i Dynamiczne Rekordy](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dynamic_dictionaries/index.md)
+- [Dynamiczne słowniki - Kolekcje i Warianty](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dynamic_dictionaries/index.md)
 - [Dokumentacja konfiguracji](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/configuration.md)

package/docs/pt/dynamic_dictionaries/index.md

@@ -1,13 +1,12 @@
 ---
 createdAt: 2026-06-12
-updatedAt: 2026-06-12
-title: Dicionários Dinâmicos
-description: Visão geral dos três recursos de dicionário dinâmico do Intlayer — coleções, variantes e registros dinâmicos — para criar conteúdo i18n flexível e orientado a runtime.
+updatedAt: 2026-06-26
+title: Dicionários dinâmicos
+description: Visão geral dos recursos de dicionários dinâmicos do Intlayer — coleções e variantes — para criar conteúdo i18n flexível e orientado em tempo de execução.
 keywords:
-  - Dicionários Dinâmicos
+  - Dicionários dinâmicos
   - Coleções
   - Variantes
-  - Registros Dinâmicos
   - Intlayer
   - Internacionalização
 slugs:
@@ -18,31 +17,38 @@ history:
   - version: 9.0.0
     date: 2026-06-12
     changes: "Lançamento do recurso de dicionários dinâmicos"
+  - version: 9.1.0
+    date: 2026-06-26
+    changes: "Fusão dos registros dinâmicos nas variantes — `variant` agora aceita uma string ou um objeto"
 author: aymericzip
 ---
 
-# Dicionários Dinâmicos
+# Dicionários dinâmicos
 
-O Intlayer suporta três mecanismos para expressar conteúdo que vai além de um único dicionário estático por chave. Cada um é declarado através de um **campo de metadados de nível superior** no arquivo de conteúdo; nenhuma função de empacotamento (wrapper) é necessária.
+O Intlayer suporta dois mecanismos para expressar conteúdo que vai além de um único dicionário estático por chave. Cada um é declarado por meio de um **campo de metadados de nível superior** no arquivo de conteúdo; nenhuma função de invólucro é necessária.
 
-| Recurso                                                                                                                      | Campo de metadados | Seletor em `useIntlayer` |
-| ---------------------------------------------------------------------------------------------------------------------------- | ------------------ | ------------------------ |
-| [Coleções](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dynamic_dictionaries/collections.md)                | `item: N`          | `{ item: N }`            |
-| [Variantes](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dynamic_dictionaries/variants.md)                  | `variant: "name"`  | `{ variant: "name" }`    |
-| [Registros Dinâmicos](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dynamic_dictionaries/dynamic_content.md) | `meta: { id, … }`  | `{ id, … }`              |
+| Recurso                                                                                                       | Campo de metadados                      | Seletor em `useIntlayer`                        |
+| ------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ----------------------------------------------- |
+| [Coleções](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dynamic_dictionaries/collections.md) | `item: N`                               | `{ item: N }`                                   |
+| [Variantes](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dynamic_dictionaries/variants.md)   | `variant: "name"` _ou_ `variant: { … }` | `{ variant: "name" }` _ou_ `{ variant: { … } }` |
 
-Todos os três se compõem com o argumento de localidade e suportam carregamento seletivo / diferido (lazy loading) via `importMode`.
+Ambos se combinam com o argumento de locale e suportam carregamento seletivo / preguiçoso via `importMode`.
 
 ## Quando usar cada um
 
-- **Coleções** — lista ordenada de itens gerenciados em arquivos separados (perguntas frequentes, posts de blog, produtos).
-- **Variantes** — alternativas de conteúdo nomeadas para testes A/B, banners sazonais ou sinalizadores de recursos (feature flags).
-- **Registros dinâmicos** — conteúdo buscado em tempo de execução por um ID opaco (registros de CMS, cópia específica do usuário).
+- **Coleções** — lista ordenada de itens gerenciados em arquivos separados (entradas de FAQ, posts de blog, produtos).
+- **Variantes** — alternativas de conteúdo nomeadas ou estruturadas:
+  - uma variante de **string** para testes A/B, banners sazonais ou feature flags;
+  - uma variante de **objeto** para registros de CMS, conteúdo específico do usuário ou qualquer conteúdo endereçado por um conjunto de campos (os antigos «registros dinâmicos»).
 
-## Desambiguação de seletores
+> Versões anteriores expunham um campo `meta` separado para conteúdo indexado por registro. Ele foi fundido em `variant`: passe um **objeto** para `variant` em vez de usar `meta`.
 
-Quando múltiplos seletores estão presentes em um dicionário, a ordem de resolução é:
+## Desambiguação do seletor
+
+Uma chave pode declarar ambas as dimensões ao mesmo tempo (por exemplo, uma coleção cujos itens têm cada um uma variante). Elas são resolvidas na ordem:
 
 ```
-variant → meta → item
+variant → item
 ```
+
+Assim, `{ variant: "promo" }` em uma chave variante × item retorna todos os itens promo como um array, e adicionar `{ item: 2 }` o restringe a uma única entrada.