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

package/docs/vi/dynamic_dictionaries/variants.md

@@ -1,13 +1,15 @@
 ---
 createdAt: 2026-06-12
-updatedAt: 2026-06-12
-title: Biến Thể
-description: Sử dụng trường siêu dữ liệu variant trong các tệp nội dung Intlayer để khai báo các lựa chọn nội dung thay thế được đặt tên (thử nghiệm A/B, biểu ngữ theo mùa, văn bản gắn cờ tính năng) và chuyển đổi giữa chúng tại runtime mà không cần thay đổi mã.
+updatedAt: 2026-06-26
+title: Biến thể
+description: Dùng trường metadata variant trong các tệp nội dung Intlayer để khai báo các lựa chọn nội dung được đặt tên hoặc có cấu trúc — thử nghiệm A/B, banner theo mùa, nội dung gắn feature flag, bản ghi CMS, nội dung riêng theo người dùng — và chuyển đổi giữa chúng trong thời gian chạy mà không cần đổi mã.
 keywords:
-  - Biến Thể
+  - Biến thể
   - Thử nghiệm A/B
-  - Cờ Tính Năng
-  - Nội Dung Động
+  - Feature Flag
+  - Nội dung động
+  - Bản ghi động
+  - CMS
   - Intlayer
   - Quốc tế hóa
 slugs:
@@ -17,17 +19,27 @@ slugs:
 history:
   - version: 9.0.0
     date: 2026-06-12
-    changes: "Phát hành tính năng từ điển biến thể"
+    changes: "Phát hành tính năng biến thể"
+  - version: 9.1.0
+    date: 2026-06-26
+    changes: "`variant` giờ chấp nhận một chuỗi hoặc một đối tượng — `meta` / bản ghi động trước đây được khai báo dưới dạng biến thể đối tượng"
 author: aymericzip
 ---
 
-# Biến Thể
+# Biến thể
 
-Một **biến thể** (variant) là một tập hợp các tệp nội dung chia sẻ cùng một khóa từ điển (`key`) nhưng mỗi tệp mang một tên `variant` khác nhau. Intlayer phục vụ tệp phù hợp dựa trên bộ chọn được truyền vào `useIntlayer`.
+Một **biến thể** là một tập hợp các tệp nội dung dùng chung `key` từ điển nhưng mỗi tệp mang một giá trị `variant` khác nhau. Intlayer phục vụ tệp phù hợp dựa trên bộ chọn được truyền cho `useIntlayer`.
 
-## Khai báo các biến thể
+Giá trị `variant` có thể có **hai dạng**:
 
-Mỗi tệp đại diện cho một lựa chọn thay thế có tên. Việc bỏ qua `variant` (hoặc đặt thành `"default"`) sẽ đánh dấu tệp đó làm phương án mặc định (fallback).
+- **Một chuỗi** — một lựa chọn được đặt tên duy nhất (thử nghiệm A/B, banner theo mùa, feature flag).
+- **Một đối tượng** — một bộ phân biệt có cấu trúc được định địa chỉ bằng một tập hợp trường (bản ghi CMS, nội dung riêng theo người dùng, bất kỳ nội dung nào được khóa bằng một ID mờ). Toàn bộ đối tượng chính là danh tính: bộ chọn phải cung cấp một đối tượng **bằng nhau** để phân giải mục.
+
+> Dạng đối tượng thay thế trường `meta` trước đây. Ở bất cứ đâu trước kia bạn viết `meta: { id, … }`, hãy viết `variant: { id, … }`, và chọn nó bằng `{ variant: { id, … } }`.
+
+## Biến thể được đặt tên (chuỗi)
+
+Mỗi tệp đại diện cho một lựa chọn được đặt tên. Bỏ qua `variant` (hoặc đặt thành `"default"`) đánh dấu nó là dự phòng.
 
 ```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;
 ```
 
-## Sử dụng biến thể
+### Sử dụng biến thể được đặt tên
 
-### Biến thể mặc định
+#### Biến thể mặc định
 
 <Tabs group="framework">
   <Tab label="React" value="react">
@@ -209,7 +221,7 @@ export default dictionary;
   </Tab>
 </Tabs>
 
-### Biến thể có tên
+#### Biến thể được đặt tên
 
 ```tsx
 const { headline, cta } = useIntlayer("hero-banner", {
@@ -217,18 +229,264 @@ const { headline, cta } = useIntlayer("hero-banner", {
 });
 ```
 
-### Biến thể có tên với ngôn ngữ cụ thể
+#### Biến thể được đặt tên với locale tường minh
 
 ```tsx
 const content = useIntlayer("hero-banner", {
   variant: "black_friday",
-  locale: "vi",
+  locale: "fr",
 });
 ```
 
+## Biến thể đối tượng (có cấu trúc)
+
+Một biến thể đối tượng định địa chỉ nội dung bằng một tập hợp cặp khóa-giá trị tùy ý được khai báo trong trường `variant` — giúp mô hình hóa bản ghi CMS, nội dung riêng theo người dùng, hoặc bất kỳ nội dung nào có khóa là một ID mờ. **Toàn bộ đối tượng** chính là danh tính: bộ chọn phải cung cấp một đối tượng bằng nhau để mục được phân giải.
+
+```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;
+```
+
+### Sử dụng biến thể đối tượng
+
+Truyền đối tượng khớp cho `variant`. Mọi trường được khai báo trên từ điển phải được cung cấp và bằng nhau; nếu không, kết quả là `null`. Thứ tự các trường không quan trọng.
+
+<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>
+
+#### Với locale tường minh
+
+```tsx
+const content = useIntlayer("product", {
+  variant: { id: "prod_abc", userId: "user_123" },
+  locale: "fr",
+});
+```
+
+#### Thiếu trường — không khớp
+
+```ts
+// Trả về null: thiếu `userId`, nên đối tượng không khớp với biến thể đã khai báo
+const content = useIntlayer("product", { variant: { id: "prod_abc" } });
+```
+
+## Chế độ tải
+
+Biến thể đối tượng thường được tải lười. Đặt `importMode` trên từ điển để kiểm soát điều này:
+
+```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;
+```
+
+Xem [tối ưu hóa bundle](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/bundle_optimization.md) để biết chi tiết về các chế độ `static`, `dynamic` và `fetch`.
+
 ## Các trường hợp sử dụng điển hình
 
-- Các thử nghiệm A/B nội dung được điều hướng bởi một khóa thử nghiệm
-- Biểu ngữ theo mùa hoặc biểu ngữ quảng cáo
-- Thông điệp được gắn cờ tính năng (feature flag)
-- Các chiến dịch tiếp thị cụ thể theo từng vùng địa lý
+- Thử nghiệm A/B nội dung được điều khiển bằng khóa thí nghiệm
+- Banner theo mùa hoặc khuyến mãi
+- Thông điệp gắn feature flag
+- Chiến dịch tiếp thị riêng theo locale
+- Nội dung tiếp thị theo từng sản phẩm được quản lý trong CMS
+- Nội dung riêng theo người dùng hoặc tài khoản
+- Bất kỳ nội dung nào được khóa bằng một ID mờ trong thời gian chạy

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

@@ -108,7 +108,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/vi/releases/v9.md

@@ -1,15 +1,14 @@
 ---
 createdAt: 2026-06-14
-updatedAt: 2026-06-25
+updatedAt: 2026-06-26
 title: Intlayer v9 Mới - Có gì mới?
-description: Khám phá các tính năng mới trong Intlayer v9. Giới thiệu các package tương thích drop-in cho các thư viện i18n phổ biến và hỗ trợ Collections, Variants, và Dynamic Records.
+description: Khám phá các tính năng mới trong Intlayer v9. Giới thiệu các package tương thích drop-in cho các thư viện i18n phổ biến và hỗ trợ Collections và Variants.
 keywords:
   - Intlayer
   - Compatibility
   - Migration
   - Collections
   - Variants
-  - Dynamic Records
   - i18next
   - next-intl
   - vue-i18n
@@ -22,7 +21,7 @@ author: aymericzip
 
 # Intlayer v9 Mới - Có gì mới?
 
-Chào mừng bạn đến với Intlayer v9! Bản phát hành lớn này đánh dấu một cột mốc quan trọng trong việc đơn giản hóa lộ trình migration sang Intlayer với các **Compat Adapter Packages** dành cho các thư viện i18n phổ biến (`react-i18next`, `next-intl`, `vue-i18n`, v.v.) và bổ sung hỗ trợ cho các cấu trúc nội dung phong phú: **Collections**, **Variants**, và **Dynamic Records**.
+Chào mừng bạn đến với Intlayer v9! Bản phát hành lớn này đánh dấu một cột mốc quan trọng trong việc đơn giản hóa lộ trình migration sang Intlayer với các **Compat Adapter Packages** dành cho các thư viện i18n phổ biến (`react-i18next`, `next-intl`, `vue-i18n`, v.v.) và bổ sung hỗ trợ cho các cấu trúc nội dung phong phú: **Collections** và **Variants**.
 
 ## Mục lục
 
@@ -41,8 +40,10 @@ Bằng cách thay thế các import, bạn sẽ nhận được tất cả các
 - `@intlayer/i18next`
 - `@intlayer/react-i18next`
 - `@intlayer/next-intl`
+- `@intlayer/react-intl`
 - `@intlayer/next-i18next`
 - `@intlayer/vue-i18n`
+- `@intlayer/lingui`
 
 Ví dụ, chỉ cần thay đổi:
 
@@ -100,7 +101,7 @@ Tất cả các compat adapter giờ đây đều định tuyến việc xử l
 
 ---
 
-## Chi tiết tính năng: Collections, Variants & Dynamic Records
+## Chi tiết tính năng: Collections & Variants
 
 Intlayer v9 mở rộng vượt ra ngoài các đối tượng key-value tĩnh, cho phép các dictionary khai báo các cấu trúc layout động được định kiểu đầy đủ (fully typed) từ đầu đến cuối.
 
@@ -144,6 +145,8 @@ const faq = useIntlayer("faq", { item: 1 }); // -> { question: string, answer: s
 
 Cung cấp các bản thử nghiệm A/B, seasonal header, feature flag, hoặc các landing page tùy chỉnh:
 
+#### Các biến thể chuỗi (ví dụ: thử nghiệm 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
-
-Định nghĩa các dictionary có các mục nhập được tải động tại runtime thông qua các query ID:
+#### Các biến thể đối tượng (ví dụ: 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**: Kích hoạt tự động khi `compiler.enabled` được đặt và một đường dẫn `compiler.output` được cấu hình. Bạn không còn cần phải đăng ký `intlayerCompiler()` riêng biệt.
+- **Compiler**: Kích hoạt tự động khi `compiler.enabled` được đặt thành `true` và một đường dẫn `compiler.output` được cấu hình. Bạn không còn cần phải đăng ký `intlayerCompiler()` riêng biệt.
 - **Proxy**: Kích hoạt tự động dựa trên tùy chọn `routing.enableProxy` mới (`true` theo mặc định). Nó kết nối middleware phát hiện ngôn ngữ / chuyển hướng / ghi đè trong phát triển, xem trước và SSR sản xuất. Bạn không còn cần phải đăng ký `intlayerProxy()` riêng biệt.
 
 ### Tùy chọn `routing.enableProxy`
@@ -252,6 +253,27 @@ Các plugin độc lập `intlayerCompiler()` và `intlayerProxy()` vẫn đư
 
 ---
 
+## Compiler bị tắt theo mặc định
+
+Kể từ Intlayer v9, **compiler bị tắt theo mặc định** (`compiler.enabled` hiện mặc định là `false`). Để bật trích xuất các file `.content.ts` của bạn tại thời điểm build, hãy đặt `compiler.enabled: true` trong cấu hình của bạn:
+
+```ts fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  compiler: {
+    enabled: true, // Mặc định: false — bắt buộc để bật compiler kể từ v9
+    output: ({ fileName }) => `./${fileName}.content.ts`,
+  },
+};
+
+export default config;
+```
+
+Khi compiler bị tắt, Intlayer bỏ qua bước trích xuất tại thời điểm build và dựa vào các dictionary mà bạn đã khai báo. Chỉ bật nó khi bạn muốn plugin bundler (`@intlayer/swc`, `@intlayer/babel`, hoặc plugin Vite `intlayer()`) tự động trích xuất nội dung.
+
+---
+
 ## React Native: import từ một package duy nhất
 
 Trong ứng dụng React Native hoặc Expo, bạn không còn cần phải xoay sở giữa `react-intlayer` và `react-native-intlayer` nữa. Package `react-native-intlayer` hiện **xuất lại toàn bộ API của `react-intlayer`** (các hook, tiện ích và các đường dẫn phụ `/format`, `/html`, và `/markdown`), và `IntlayerProvider` của nó tự động áp dụng các polyfill của React Native.
@@ -278,13 +300,14 @@ npm install intlayer react-native-intlayer
 
 Nếu bạn đang nâng cấp từ v8, lưu ý rằng v9 không bao gồm các breaking change. Tuy nhiên, dưới đây là các thay đổi chính:
 
+- **Compiler bị tắt theo mặc định**: `compiler.enabled` hiện mặc định là `false`. Nếu bạn dựa vào việc trích xuất các file `.content.ts` tại thời điểm build, hãy đặt `compiler.enabled: true` trong `intlayer.config.ts` của bạn.
 - **Locales & Dialects**: Nếu sử dụng các dependency i18n bên ngoài, hãy thêm các compat adapter plugin tương ứng của chúng vào cấu hình hoặc thiết lập bundler của bạn để tự động rewrite các import.
-- **Custom Selectors**: Khi gọi `useIntlayer`, tham số thứ hai giờ đây được dành riêng cho một đối tượng option chứa `{ locale, item, variant, id }`. Nếu trước đây bạn đã truyền trực tiếp một chuỗi locale, bạn vẫn có thể làm như vậy, nhưng việc sử dụng đối tượng options được khuyến nghị cho các lựa chọn nâng cao.
+- **Custom Selectors**: Khi gọi `useIntlayer`, tham số thứ hai giờ đây được dành riêng cho một đối tượng option chứa `{ locale, item, variant }`. Nếu trước đây bạn đã truyền trực tiếp một chuỗi locale, bạn vẫn có thể làm như vậy, nhưng việc sử dụng đối tượng options được khuyến nghị cho các lựa chọn nâng cao.
 
 ---
 
 ## Liên kết hữu ích
 
 - [Hướng dẫn về Compat Adapter Packages](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/compat/index.md)
-- [Dynamic Dictionaries - Collections, Variants & Dynamic Records](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/dynamic_dictionaries/index.md)
+- [Dynamic Dictionaries - Collections & Variants](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/dynamic_dictionaries/index.md)
 - [Tài liệu tham khảo cấu hình](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/configuration.md)

package/docs/zh/dynamic_dictionaries/index.md

@@ -1,13 +1,12 @@
 ---
 createdAt: 2026-06-12
-updatedAt: 2026-06-12
+updatedAt: 2026-06-26
 title: 动态字典
-description: Intlayer 的三种动态字典功能 — 集合、变体和动态记录 — 概述，用于构建灵活、运行时驱动的 i18n 内容。
+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 支持三种机制来表达超出每个键单个静态字典范围的内容。每种机制都是通过内容文件中的**顶层元数据字段**声明 ponder 的；不需要包装函数。
+Intlayer 支持两种机制来表达超出每个键单一静态字典的内容。每种机制都通过内容文件中的**顶层元数据字段**声明；无需包装函数。
 
-| 功能                                                                                                              | 元数据字段        | `useIntlayer` 中的选择器 |
-| ----------------------------------------------------------------------------------------------------------------- | ----------------- | ------------------------ |
-| [集合](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dynamic_dictionaries/collections.md)         | `item: N`         | `{ item: N }`            |
-| [变体](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dynamic_dictionaries/variants.md)            | `variant: "name"` | `{ variant: "name" }`    |
-| [动态记录](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dynamic_dictionaries/dynamic_content.md) | `meta: { id, … }` | `{ id, … }`              |
+| 功能                                                                                                      | 元数据字段                              | `useIntlayer` 中的选择器                        |
+| --------------------------------------------------------------------------------------------------------- | --------------------------------------- | ----------------------------------------------- |
+| [集合](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dynamic_dictionaries/collections.md) | `item: N`                               | `{ item: N }`                                   |
+| [变体](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dynamic_dictionaries/variants.md)    | `variant: "name"` _或_ `variant: { … }` | `{ variant: "name" }` _或_ `{ variant: { … } }` |
 
-这三种机制都与语言环境参数结合使用，并支持通过 `importMode` 进行选择性/延迟加载。
+两者都可与 locale 参数组合，并支持通过 `importMode` 进行选择性 / 惰性加载。
 
-## 什么时候使用哪一个
+## 何时使用哪一个
 
-- **集合** — 在单独文件中管理的有序项目列表（常见问题条目、博客文章、产品）。
-- **变体** — 用于 A/B 测试、季节性横幅或功能标志（feature flags）的命名内容替代方案。
-- **动态记录** — 在运行时通过不透明 ID 获取的内容（CMS 记录、用户特定文案）。
+- **集合** — 在单独文件中管理的有序项目列表（FAQ 条目、博客文章、产品）。
+- **变体** — 具名或结构化的内容替代项：
+  - 用于 A/B 测试、季节性横幅或功能开关的**字符串**变体；
+  - 用于 CMS 记录、用户特定文案，或由一组字段寻址的任何内容的**对象**变体（即以前的“动态记录”）。
 
-## 选择器消除歧义
+> 早期版本为按记录键控的内容提供单独的 `meta` 字段。它已合并到 `variant` 中：向 `variant` 传递一个**对象**，而不是使用 `meta`。
 
-当字典中存在多个选择器时，解析顺序为：
+## 选择器消歧
+
+一个键可以同时声明两个维度（例如每个项目都有变体的集合）。它们按以下顺序解析：
 
 ```
-variant → meta → item
+variant → item
 ```
+
+因此，对 variant × item 键使用 `{ variant: "promo" }` 会以数组形式返回所有 promo 项目，而添加 `{ item: 2 }` 则将其缩小到单个条目。