@intlayer/docs 9.0.0-canary.2 → 9.0.0-canary.21

package/docs/zh/dictionary/insertion.md

@@ -152,70 +152,6 @@ export default InsertionComponent;
 
 ## 附加资源
 
-有关配置和使用的更详细信息，请参阅以下资源：
-
-- [Intlayer CLI 文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/index.md)
-  const { useIntlayer } = require("react-intlayer");
-
-const InsertionComponent = () => {
-const { myInsertion } = useIntlayer("my_key");
-
-return (
-
-<div>
-<p>
-{
-/_ 输出: "Hello, my name is John and I am 30 years old!" _/
-myInsertion({ name: "John", age: "30" })
-}
-</p>
-<p>
-{
-/_ 你可以使用不同的值重复使用相同的插入 _/
-myInsertion({ name: "Alice", age: "25" })
-}
-</p>
-</div>
-);
-};
-
-module.exports = InsertionComponent;
-
-```
-
-## 附加资源
-
-有关配置和使用的更详细信息，请参阅以下资源：
-
-- [Intlayer CLI 文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/index.md)
-const { useIntlayer } = require("react-intlayer");
-
-const InsertionComponent = () => {
-  const { myInsertion } = useIntlayer("my_key");
-
-  return (
-    <div>
-      <p>
-        {
-          /* 输出: "Hello, my name is John and I am 30 years old!" */
-          myInsertion({ name: "John", age: "30" })
-        }
-      </p>
-      <p>
-        {
-          /* 你可以使用不同的值重复使用相同的插入 */
-          myInsertion({ name: "Alice", age: "25" })
-        }
-      </p>
-    </div>
-  );
-};
-
-module.exports = InsertionComponent;
-```
-
-## 附加资源
-
 有关配置和使用的更详细信息，请参考以下资源：
 
 - [Intlayer CLI 文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/index.md)

package/docs/zh/dictionary/nesting.md

@@ -27,6 +27,45 @@ author: aymericzip
 
 ## 设置嵌套
 
+要在你的 Intlayer 项目中设置嵌套，你首先定义你希望重用的基础内容。然后，在一个单独的内容模块中，你使用 `nest` 函数来导入该内容。
+
+### 基础字典
+
+下面是一个基础字典的示例，用于嵌套在另一个字典中：
+
+```typescript fileName="firstDictionary.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+import { type Dictionary } from "intlayer";
+
+const firstDictionary = {
+  key: "key_of_my_first_dictionary",
+  content: {
+    content: "content",
+    subContent: {
+      contentNumber: 0,
+      contentString: "string",
+    },
+  },
+} satisfies Dictionary;
+
+export default firstDictionary;
+```
+
+```json fileName="firstDictionary.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "key_of_my_first_dictionary",
+  "content": {
+    "content": "content",
+    "subContent": {
+      "contentNumber": 0,
+      "contentString": "string"
+    }
+  }
+}
+```
+
+## 设置嵌套
+
 <Tabs group="framework">
   <Tab label="React" value="react">
 

package/docs/zh/dictionary/translation.md

@@ -259,87 +259,3 @@ document.getElementById("welcome-message")!.textContent = String(
 
   </Tab>
 </Tabs>
-
-## 在 React 组件中使用翻译
-
-使用 `react-intlayer`，您可以在 React 组件中使用翻译。示例如下：
-
-```jsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
-import type { FC } from "react";
-import { useIntlayer } from "react-intlayer";
-
-const MyComponent: FC = () => {
-  const content = useIntlayer("multi_lang");
-
-  return (
-    <div>
-      <p>{content.welcomeMessage}</p>
-    </div>
-  );
-};
-
-export default MyComponent;
-```
-
-该组件根据您应用中设置的当前语言环境获取相应的翻译内容。
-
-## 自定义内容对象
-
-`intlayer` 支持用于翻译的自定义内容对象，允许您定义更复杂的结构，同时确保类型安全。以下是一个自定义对象的示例：
-
-```typescript fileName="**/*.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
-import { t, type Dictionary } from "intlayer";
-
-interface ICustomContent {
-  title: string;
-  content: string;
-}
-
-const customContent = {
-  key: "custom_content",
-  content: {
-    profileText: t<ICustomContent>({
-      en: {
-        title: "页面标题",
-        content: "页面内容",
-      },
-      fr: {
-        title: "Titre de la Page",
-        content: "Contenu de la Page",
-      },
-      es: {
-        title: "页面标题",
-        content: "页面内容",
-      },
-    }),
-  },
-} satisfies Dictionary;
-
-export default customContent;
-```
-
-```json fileName="**/*.content.json" contentDeclarationFormat="json"
-{
-  "$schema": "https://intlayer.org/schema.json",
-  "key": "custom_content",
-  "content": {
-    "profileText": {
-      "nodeType": "translation",
-      "translation": {
-        "en": {
-          "title": "页面标题",
-          "content": "页面内容"
-        },
-        "fr": {
-          "title": "页面标题",
-          "content": "页面内容"
-        },
-        "es": {
-          "title": "页面标题",
-          "content": "页面内容"
-        }
-      }
-    }
-  }
-}
-```

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 作为键的任何内容