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

package/docs/ko/dynamic_dictionaries/variants.md

@@ -1,13 +1,15 @@
 ---
 createdAt: 2026-06-12
-updatedAt: 2026-06-12
+updatedAt: 2026-06-26
 title: 변형
-description: 코드 변경 없이 런타임에 서로 전환할 수 있는 이름이 지정된 대체 콘텐츠(A/B 테스트, 시즌별 배너, 기능 플래그가 지정된 텍스트)를 선언하기 위해 Intlayer 콘텐츠 파일에서 variant 메타데이터 필드를 사용합니다.
+description: Intlayer 콘텐츠 파일에서 variant 메타데이터 필드를 사용하여 이름이 지정되었거나 구조화된 콘텐츠 대안 — A/B 테스트, 시즌 배너, 기능 플래그 텍스트, CMS 레코드, 사용자별 콘텐츠 — 을 선언하고 코드 변경 없이 런타임에 전환합니다.
 keywords:
   - 변형
   - A/B 테스트
   - 기능 플래그
   - 동적 콘텐츠
+  - 동적 레코드
+  - CMS
   - Intlayer
   - 국제화
 slugs:
@@ -17,17 +19,27 @@ slugs:
 history:
   - version: 9.0.0
     date: 2026-06-12
-    changes: "변형 사전 기능 출시"
+    changes: "변형 기능 출시"
+  - version: 9.1.0
+    date: 2026-06-26
+    changes: "이제 `variant`는 문자열 또는 객체를 허용합니다 — 이전의 `meta` / 동적 레코드는 객체 변형으로 선언됩니다"
 author: aymericzip
 ---
 
 # 변형
 
-**변형**(Variant)은 동일한 사전 키(`key`)를 공유하지만 서로 다른 `variant` 이름을 선언하는 콘텐츠 파일의 집합입니다. Intlayer는 `useIntlayer`에 전달된 선택기에 따라 적절한 파일을 서비스합니다.
+**변형**은 동일한 사전 `key`를 공유하지만 각각 다른 `variant` 값을 갖는 콘텐츠 파일의 집합입니다. Intlayer는 `useIntlayer`에 전달된 셀렉터에 따라 적절한 파일을 제공합니다.
 
-## 변형 선언
+`variant` 값은 **두 가지 형태**를 가질 수 있습니다:
 
-각 파일은 하나의 이름이 지정된 대체 콘텐츠를 나타냅니다. `variant` 필드를 생략하거나 `"default"`로 설정하면 기본(fallback) 변형으로 표시됩니다.
+- **문자열** — 단일 이름 지정 대안(A/B 테스트, 시즌 배너, 기능 플래그).
+- **객체** — 필드 집합으로 주소가 지정되는 구조화된 판별자(CMS 레코드, 사용자별 콘텐츠, 불투명한 ID로 키가 지정된 모든 콘텐츠). 객체 전체가 정체성입니다. 항목을 해결하려면 셀렉터가 **동일한** 객체를 제공해야 합니다.
+
+> 객체 형태는 이전의 `meta` 필드를 대체합니다. 이전에 `meta: { id, … }`를 작성했던 모든 곳에서 `variant: { id, … }`를 작성하고 `{ variant: { id, … } }`로 선택하세요.
+
+## 이름 지정(문자열) 변형
+
+각 파일은 하나의 이름 지정 대안을 나타냅니다. `variant`를 생략하거나(`"default"`로 설정하면) 폴백으로 표시됩니다.
 
 ```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;
 ```
 
-## 변형 소비하기
+### 이름 지정 변형 사용
 
-### 기본 변형
+#### 기본 변형
 
 <Tabs group="framework">
   <Tab label="React" value="react">
@@ -209,7 +221,7 @@ export default dictionary;
   </Tab>
 </Tabs>
 
-### 이름이 지정된 변형
+#### 이름 지정 변형
 
 ```tsx
 const { headline, cta } = useIntlayer("hero-banner", {
@@ -217,18 +229,264 @@ const { headline, cta } = useIntlayer("hero-banner", {
 });
 ```
 
-### 명시적 로케일로 이름이 지정된 변형
+#### 명시적 로케일이 있는 이름 지정 변형
 
 ```tsx
 const content = useIntlayer("hero-banner", {
   variant: "black_friday",
-  locale: "ko",
+  locale: "fr",
 });
 ```
 
+## 객체(구조화) 변형
+
+객체 변형은 `variant` 필드에 선언된 임의의 키-값 쌍 집합으로 콘텐츠의 주소를 지정합니다 — 이를 통해 CMS 레코드, 사용자별 콘텐츠, 또는 키가 불투명한 ID인 모든 콘텐츠를 모델링할 수 있습니다. **객체 전체**가 정체성입니다. 항목이 해결되려면 셀렉터가 동일한 객체를 제공해야 합니다.
+
+```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;
+```
+
+### 객체 변형 사용
+
+일치하는 객체를 `variant`에 전달하세요. 사전에 선언된 모든 필드를 제공해야 하며 동일해야 합니다. 그렇지 않으면 결과는 `null`입니다. 필드 순서는 중요하지 않습니다.
+
+<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>
+
+#### 명시적 로케일과 함께
+
+```tsx
+const content = useIntlayer("product", {
+  variant: { id: "prod_abc", userId: "user_123" },
+  locale: "fr",
+});
+```
+
+#### 누락된 필드 — 일치 없음
+
+```ts
+// null 반환: `userId`가 누락되어 객체가 선언된 변형과 일치하지 않습니다
+const content = useIntlayer("product", { variant: { id: "prod_abc" } });
+```
+
+## 로딩 모드
+
+객체 변형은 종종 지연 로드됩니다. 이를 제어하려면 사전에 `importMode`를 설정하세요:
+
+```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;
+```
+
+`static`, `dynamic`, `fetch` 모드에 대한 자세한 내용은 [번들 최적화](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/bundle_optimization.md)를 참조하세요.
+
 ## 일반적인 사용 사례
 
-- 실험 키(experiment key)에 따른 A/B 카피 테스트
-- 시즌별 또는 프로모션 배너
-- 기능 플래그(feature flags)로 제어되는 문구
-- 특정 로케일 타겟 마케팅 캠페인
+- 실험 키로 구동되는 A/B 카피 테스트
+- 시즌 또는 프로모션 배너
+- 기능 플래그 메시지
+- 로케일별 마케팅 캠페인
+- CMS에서 관리되는 제품별 마케팅 카피
+- 사용자별 또는 계정별 콘텐츠
+- 런타임에 불투명한 ID로 키가 지정된 모든 콘텐츠

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

@@ -108,7 +108,6 @@ const config: IntlayerConfig = {
      * 출력 및 번역을 로케일 디렉토리의 JSON 파일로 로드하고 다시 씁니다.
      */
     syncJSON({
-      format: "i18next",
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
       priority: 0,
       format: "i18next",

package/docs/ko/releases/v9.md

@@ -1,15 +1,14 @@
 ---
 createdAt: 2026-06-14
-updatedAt: 2026-06-25
+updatedAt: 2026-06-26
 title: 새로운 Intlayer v9 - 무엇이 달라졌나요?
-description: Intlayer v9의 새로운 기능을 알아보세요. 인기 있는 i18n 라이브러리를 위한 드롭인 호환성 패키지와 컬렉션(Collections), 베리언트(Variants), 동적 레코드(Dynamic Records) 지원을 소개합니다.
+description: Intlayer v9의 새로운 기능을 알아보세요. 인기 있는 i18n 라이브러리를 위한 드롭인 호환성 패키지와 컬렉션(Collections), 베리언트(Variants) 지원을 소개합니다.
 keywords:
   - Intlayer
   - 호환성
   - 마이그레이션
   - 컬렉션
   - 베리언트
-  - 동적 레코드
   - i18next
   - next-intl
   - vue-i18n
@@ -22,7 +21,7 @@ author: aymericzip
 
 # 새로운 Intlayer v9 - 무엇이 달라졌나요?
 
-Intlayer v9에 오신 것을 환영합니다! 이번 메이저 릴리스는 주요 i18n 라이브러리(`react-i18next`, `next-intl`, `vue-i18n` 등)를 위한 **호환 어댑터 패키지(Compat Adapter Packages)**를 통해 Intlayer로의 마이그레이션 경로를 획기적으로 단순화하고, **컬렉션(Collections)**, **베리언트(Variants)**, **동적 레코드(Dynamic Records)**와 같은 풍부한 콘텐츠 구조 지원을 추가하는 큰 이정표를 세웠습니다.
+Intlayer v9에 오신 것을 환영합니다! 이번 메이저 릴리스는 주요 i18n 라이브러리(`react-i18next`, `next-intl`, `vue-i18n` 등)를 위한 **호환 어댑터 패키지(Compat Adapter Packages)**를 통해 Intlayer로의 마이그레이션 경로를 획기적으로 단순화하고, **컬렉션(Collections)** 및 **베리언트(Variants)**와 같은 풍부한 콘텐츠 구조 지원을 추가하는 큰 이정표를 세웠습니다.
 
 ## 목차
 
@@ -41,8 +40,10 @@ Intlayer v9에 오신 것을 환영합니다! 이번 메이저 릴리스는 주
 - `@intlayer/i18next`
 - `@intlayer/react-i18next`
 - `@intlayer/next-intl`
+- `@intlayer/react-intl`
 - `@intlayer/next-i18next`
 - `@intlayer/vue-i18n`
+- `@intlayer/lingui`
 
 예를 들어, 다음과 같이 간단히 변경하면 됩니다:
 
@@ -100,7 +101,7 @@ export default defineConfig({
 
 ---
 
-## 기능 사양: 컬렉션, 베리언트 및 동적 레코드
+## 기능 사양: 컬렉션 및 베리언트
 
 Intlayer v9은 정적인 키-값 객체를 넘어, 딕셔너리가 처음부터 끝까지 완전히 타입 지정된 동적 레이아웃 구조를 선언할 수 있도록 확장되었습니다.
 
@@ -144,6 +145,8 @@ const faq = useIntlayer("faq", { item: 1 }); // -> { question: string, answer: s
 
 A/B 테스트, 시즌별 헤더, 피처 플래그(feature flags) 또는 커스텀 랜딩 페이지를 제공합니다:
 
+#### 문자열 베리언트 (예: 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)
-
-쿼리 ID를 통해 런타임에 동적으로 로드되는 항목을 가진 딕셔너리를 정의합니다:
+#### 객체 베리언트 (예: 동적 레코드)
 
 ```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**: `compiler.enabled`가 설정되고 `compiler.output` 경로가 구성되면 자동으로 활성화됩니다. 더 이상 `intlayerCompiler()`를 별도로 등록할 필요가 없습니다.
+- **Compiler**: `compiler.enabled`가 `true`로 설정되고 `compiler.output` 경로가 구성되면 자동으로 활성화됩니다. 더 이상 `intlayerCompiler()`를 별도로 등록할 필요가 없습니다.
 - **Proxy**: 새로운 `routing.enableProxy` 옵션(`기본값: true`)을 기반으로 자동으로 활성화됩니다. 개발, 미리보기 및 프로덕션 SSR에서 로케일 감지 / 리다이렉트 / 재작성 미들웨어를 연결합니다. 더 이상 `intlayerProxy()`를 별도로 등록할 필요가 없습니다.
 
 ### `routing.enableProxy` 옵션
@@ -252,6 +253,27 @@ export default config;
 
 ---
 
+## 컴파일러는 기본적으로 비활성화
+
+Intlayer v9부터 **컴파일러는 기본적으로 비활성화됩니다**(`compiler.enabled`의 기본값이 이제 `false`입니다). `.content.ts` 파일의 빌드 타임 추출을 활성화하려면 구성에서 `compiler.enabled: true`를 설정하세요:
+
+```ts fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  compiler: {
+    enabled: true, // 기본값: false — v9부터 컴파일러를 활성화하는 데 필요
+    output: ({ fileName }) => `./${fileName}.content.ts`,
+  },
+};
+
+export default config;
+```
+
+컴파일러가 비활성화되면 Intlayer는 빌드 타임 추출 단계를 건너뛰고 이미 선언한 딕셔너리에 의존합니다. 번들러 플러그인(`@intlayer/swc`, `@intlayer/babel` 또는 `intlayer()` Vite 플러그인)이 콘텐츠를 자동으로 추출하기를 원할 때만 활성화하세요.
+
+---
+
 ## React Native: 단일 패키지 임포트
 
 React Native 또는 Expo 앱에서는 더 이상 `react-intlayer`와 `react-native-intlayer`를 번갈아 사용할 필요가 없습니다. `react-native-intlayer` 패키지는 이제 **`react-intlayer`의 전체 API를 다시 내보내며** (훅, 유틸리티 및 `/format`, `/html`, `/markdown` 하위 경로), `IntlayerProvider`는 React Native 폴리필을 자동으로 적용합니다.
@@ -278,13 +300,14 @@ npm install intlayer react-native-intlayer
 
 v8에서 업그레이드하는 경우, v9에는 하위 호환성을 깨뜨리는 변경 사항(breaking changes)이 포함되어 있지 않습니다. 하지만 다음과 같은 주요 변경 사항이 있습니다:
 
+- **컴파일러는 기본적으로 비활성화**: `compiler.enabled`의 기본값이 이제 `false`입니다. `.content.ts` 파일의 빌드 타임 추출에 의존하는 경우 `intlayer.config.ts`에서 `compiler.enabled: true`를 설정하세요.
 - **로케일 및 다이얼렉트 (Locales & Dialects)**: 외부 i18n 의존성을 사용하는 경우, 설정 또는 번들러 구성에 해당 호환 어댑터 플러그인을 추가하여 임포트를 자동으로 변환하세요.
-- **커스텀 셀렉터 (Custom Selectors)**: `useIntlayer`를 호출할 때 두 번째 매개변수는 이제 `{ locale, item, variant, id }`를 포함하는 옵션 객체 전용으로 예약됩니다. 이전에 로케일 문자열을 직접 전달했다면 여전히 그렇게 사용할 수 있지만, 고급 선택을 위해서는 옵션 객체를 사용하는 것을 권장합니다.
+- **커스텀 셀렉터 (Custom Selectors)**: `useIntlayer`를 호출할 때 두 번째 매개변수는 이제 `{ locale, item, variant }`를 포함하는 옵션 객체 전용으로 예약됩니다. 이전에 로케일 문자열을 직접 전달했다면 여전히 그렇게 사용할 수 있지만, 고급 선택을 위해서는 옵션 객체를 사용하는 것을 권장합니다.
 
 ---
 
 ## 유용한 링크
 
 - [호환 어댑터 패키지 가이드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/compat/index.md)
-- [동적 딕셔너리 - 컬렉션, 베리언트 및 동적 레코드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dynamic_dictionaries/index.md)
+- [동적 딕셔너리 - 컬렉션 및 베리언트](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dynamic_dictionaries/index.md)
 - [설정 레퍼런스](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/configuration.md)

package/docs/pl/dynamic_dictionaries/index.md

@@ -1,15 +1,14 @@
 ---
 createdAt: 2026-06-12
-updatedAt: 2026-06-12
-title: Słowniki Dynamiczne
-description: Omówienie trzech funkcji dynamicznych słowników w Intlayer — kolekcji, wariantów i rekordów dynamicznych — do budowania elastycznych, sterowanych w czasie wykonania treści i18n.
+updatedAt: 2026-06-26
+title: Słowniki dynamiczne
+description: Przegląd funkcji słowników dynamicznych Intlayer — kolekcji i wariantów — do tworzenia elastycznej, sterowanej w czasie wykonywania treści i18n.
 keywords:
-  - Słowniki Dynamiczne
+  - Słowniki dynamiczne
   - Kolekcje
   - Warianty
-  - Rekordy Dynamiczne
   - Intlayer
-  - Umiędzynarodowienie
+  - Internacjonalizacja
 slugs:
   - doc
   - concept
@@ -18,31 +17,38 @@ history:
   - version: 9.0.0
     date: 2026-06-12
     changes: "Wydanie funkcji słowników dynamicznych"
+  - version: 9.1.0
+    date: 2026-06-26
+    changes: "Scalono rekordy dynamiczne z wariantami — `variant` przyjmuje teraz ciąg znaków lub obiekt"
 author: aymericzip
 ---
 
-# Słowniki Dynamiczne
+# Słowniki dynamiczne
 
-Intlayer obsługuje trzy mechanizmy definiowania treści wykraczających poza pojedynczy, statyczny słownik na klucz. Każdy z nich jest deklarowany poprzez **pole metadanych najwyższego poziomu** w pliku zawartości; funkcja opakowująca (wrapper) nie jest wymagana.
+Intlayer obsługuje dwa mechanizmy wyrażania treści wykraczającej poza pojedynczy statyczny słownik na klucz. Każdy jest deklarowany przez **pole metadanych najwyższego poziomu** w pliku treści; nie jest potrzebna żadna funkcja opakowująca.
 
-| Funkcja                                                                                                                     | Pole metadanych   | Selektor w `useIntlayer` |
-| --------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------------------------ |
-| [Kolekcje](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dynamic_dictionaries/collections.md)               | `item: N`         | `{ item: N }`            |
-| [Warianty](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dynamic_dictionaries/variants.md)                  | `variant: "name"` | `{ variant: "name" }`    |
-| [Rekordy Dynamiczne](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dynamic_dictionaries/dynamic_content.md) | `meta: { id, … }` | `{ id, … }`              |
+| Funkcja                                                                                                       | Pole metadanych                          | Selektor w `useIntlayer`                         |
+| ------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ------------------------------------------------ |
+| [Kolekcje](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dynamic_dictionaries/collections.md) | `item: N`                                | `{ item: N }`                                    |
+| [Warianty](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dynamic_dictionaries/variants.md)    | `variant: "name"` _lub_ `variant: { … }` | `{ variant: "name" }` _lub_ `{ variant: { … } }` |
 
-Wszystkie trzy łączą się z argumentem lokalizacji i obsługują wybiórcze / leniwe ładowanie (lazy loading) za pomocą `importMode`.
+Oba łączą się z argumentem locale i obsługują selektywne / leniwe ładowanie przez `importMode`.
 
-## Kiedy używać którego rozwiązania
+## Kiedy czego używać
 
 - **Kolekcje** — uporządkowana lista elementów zarządzanych w osobnych plikach (wpisy FAQ, posty na blogu, produkty).
-- **Warianty** — nazwane alternatywy treści dla testów A/B, banerów sezonowych lub flag funkcji (feature flags).
-- **Rekordy dynamiczne** — treści pobierane w czasie wykonania za pomocą nieprzezroczystego identyfikatora ID (rekordy CMS, treści specyficzne dla użytkownika).
+- **Warianty** — nazwane lub strukturalne alternatywy treści:
+  - wariant **tekstowy** do testów A/B, banerów sezonowych lub feature flag;
+  - wariant **obiektowy** dla rekordów CMS, treści zależnej od użytkownika lub dowolnej treści adresowanej zestawem pól (dawne „rekordy dynamiczne").
 
-## Rozstrzyganie konfliktów selektorów
+> Wcześniejsze wersje udostępniały osobne pole `meta` dla treści indeksowanej rekordami. Zostało scalone z `variant`: przekaż do `variant` **obiekt** zamiast używać `meta`.
 
-Gdy słownik posiada wiele selektorów, kolejność ich rozstrzygania to:
+## Ujednoznacznianie selektora
+
+Klucz może deklarować obydwa wymiary jednocześnie (np. kolekcja, której elementy mają wariant). Są one rozwiązywane w kolejności:
 
 ```
-variant → meta → item
+variant → item
 ```
+
+Zatem `{ variant: "promo" }` dla klucza variant × item zwraca wszystkie elementy promo jako tablicę, a dodanie `{ item: 2 }` zawęża wynik do pojedynczego wpisu.