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

package/docs/vi/releases/v9.md

@@ -1,15 +1,14 @@
 ---
 createdAt: 2026-06-14
-updatedAt: 2026-06-23
+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,17 +253,61 @@ 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.
+
+Import mọi thứ từ package `react-native-intlayer` duy nhất:
+
+```tsx
+import {
+  IntlayerProvider,
+  useIntlayer,
+  useLocale,
+} from "react-native-intlayer";
+```
+
+```bash
+npm install intlayer react-native-intlayer
+```
+
+> Việc import từ `react-intlayer` vẫn tiếp tục hoạt động, nhưng `react-native-intlayer` hiện là điểm vào duy nhất được khuyên dùng cho React Native — provider của nó cung cấp các polyfill mà provider định hướng web `react-intlayer` không có.
+
+---
+
 ## Lưu ý khi migration từ v8
 
 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/compiler.md

@@ -81,12 +81,15 @@ npm install vite-intlayer
 
 ```ts fileName="vite.config.ts"
 import { defineConfig } from "vite";
-import { intlayer, intlayerCompiler } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
   plugins: [
-    intlayer(),
-    intlayerCompiler(), // 添加编译器插件
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 });
 ```

package/docs/zh/custom_domains.md

@@ -172,10 +172,16 @@ GET intlayer.zh/about
 
 ```typescript fileName="vite.config.ts"
 import { defineConfig } from "vite";
-import { intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
-  plugins: [intlayerProxy()],
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
 });
 ```
 

package/docs/zh/custom_url_rewrites.md

@@ -342,10 +342,16 @@ export function middleware(request: NextRequest) {
 
 ```typescript fileName="vite.config.ts"
 import { defineConfig } from "vite";
-import { intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
-  plugins: [intlayerProxy()],
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
 });
 ```
 

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 }` 则将其缩小到单个条目。

package/docs/zh/dynamic_dictionaries/variants.md

@@ -1,13 +1,15 @@
 ---
 createdAt: 2026-06-12
-updatedAt: 2026-06-12
+updatedAt: 2026-06-26
 title: 变体
-description: 在 Intlayer 内容文件中使用 variant 元数据字段来声明命名内容替代方案（A/B 测试、季节性横幅、受功能标志控制的文案），并在运行时切换它们而无需更改代码。
+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"`），则表示它是默认（回退）变体。
+- **字符串** — 单个具名替代项（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: "zh",
+  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/zh/bundle_optimization.md)。
+
+## 典型用例
 
-- 由实验键值驱动的文案 A/B 测试
+- 由实验键驱动的 A/B 文案测试
 - 季节性或促销横幅
-- 受功能标志（feature flags）控制的消息文案
-- 针对特定区域的营销活动
+- 功能开关消息
+- 特定语言环境的营销活动
+- 在 CMS 中管理的按产品营销文案
+- 用户特定或账户特定的内容
+- 在运行时以不透明 ID 作为键的任何内容

package/docs/zh/intlayer_with_astro.md

@@ -539,6 +539,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel 编译器'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 更新您的 `vite.config.ts` 以包含 `intlayerCompiler` 插件：
 
 ```ts fileName="vite.config.ts"
@@ -548,7 +550,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 添加编译器插件
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/zh/intlayer_with_astro_lit.md

@@ -590,6 +590,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel 编译器'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 更新您的 `vite.config.ts` 以包含 `intlayerCompiler` 插件：
 
 ```ts fileName="vite.config.ts"
@@ -599,7 +601,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 添加编译器插件
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/zh/intlayer_with_astro_preact.md

@@ -545,6 +545,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel 编译器'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 更新您的 `vite.config.ts` 以包含 `intlayerCompiler` 插件：
 
 ```ts fileName="vite.config.ts"
@@ -554,7 +556,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 添加编译器插件
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```