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

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/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/zh/releases/v9.md

@@ -1,15 +1,14 @@
 ---
 createdAt: 2026-06-14
-updatedAt: 2026-06-25
+updatedAt: 2026-06-26
 title: New Intlayer v9 - What's new?
-description: Discover what's new in Intlayer v9. Introducing drop-in compatibility packages for popular i18n libraries and support for Collections, Variants, and Dynamic Records.
+description: Discover what's new in Intlayer v9. Introducing drop-in compatibility packages for popular i18n libraries and support for Collections and Variants.
 keywords:
   - Intlayer
   - Compatibility
   - Migration
   - Collections
   - Variants
-  - Dynamic Records
   - i18next
   - next-intl
   - vue-i18n
@@ -22,7 +21,7 @@ author: aymericzip
 
 # New Intlayer v9 - What's new?
 
-Welcome to Intlayer v9! This major release marks a huge milestone in simplifying the migration path to Intlayer with **Compat Adapter Packages** for major i18n libraries (`react-i18next`, `next-intl`, `vue-i18n`, etc.) and adds support for rich content structures: **Collections**, **Variants**, and **Dynamic Records**.
+Welcome to Intlayer v9! This major release marks a huge milestone in simplifying the migration path to Intlayer with **Compat Adapter Packages** for major i18n libraries (`react-i18next`, `next-intl`, `vue-i18n`, etc.) and adds support for rich content structures: **Collections** and **Variants**.
 
 ## Table of contents
 
@@ -41,8 +40,10 @@ By replacing imports, you get all the benefits of Intlayer (including compile-ti
 - `@intlayer/i18next`
 - `@intlayer/react-i18next`
 - `@intlayer/next-intl`
+- `@intlayer/react-intl`
 - `@intlayer/next-i18next`
 - `@intlayer/vue-i18n`
+- `@intlayer/lingui`
 
 For example, simply change:
 
@@ -100,7 +101,7 @@ All compat adapters now route translation resolution through a single, highly op
 
 ---
 
-## Feature Spec: Collections, Variants & Dynamic Records
+## Feature Spec: Collections & Variants
 
 Intlayer v9 expands beyond static key-value objects, allowing dictionaries to declare dynamic layout structures that are fully typed end-to-end.
 
@@ -136,6 +137,8 @@ const faq = useIntlayer("faq", { item: 1 }); // -> { question: string, answer: s
 
 Deliver A/B tests, seasonal headers, feature flags, or custom landing pages:
 
+#### String variants (e.g. A/B testing)
+
 ```ts fileName="hero.content.ts"
 import { t, type Dictionary } from "intlayer";
 
@@ -155,16 +158,14 @@ export default {
 const banner = useIntlayer("hero-banner", { variant: "black_friday" });
 ```
 
-### 3. Dynamic Records
-
-Define dictionaries whose entries are loaded dynamically at runtime via query IDs:
+#### Object variants (e.g. 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",
   },
@@ -217,7 +218,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` 选项
@@ -240,6 +241,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**（hooks、工具函数以及 `/format`、`/html` 和 `/markdown` 子路径），并且其 `IntlayerProvider` 会自动应用 React Native 的 polyfills。
@@ -266,13 +288,14 @@ npm install intlayer react-native-intlayer
 
 If you are upgrading from v8, note that the v9 does not include breaking changes. But here are the key changes:
 
+- **默认禁用编译器**：`compiler.enabled` 现在默认为 `false`。如果您依赖对 `.content.ts` 文件的构建时提取，请在 `intlayer.config.ts` 中设置 `compiler.enabled: true`。
 - **Locales & Dialects**: If using external i18n dependencies, add their respective compat adapter plugins in your configuration or bundler setup to automatically rewrite imports.
-- **Custom Selectors**: When calling `useIntlayer`, the second parameter is now reserved for an option object containing `{ locale, item, variant, id }`. If you previously passed a locale string directly, you can still do so, but using the options object is recommended for advanced selections.
+- **Custom Selectors**: When calling `useIntlayer`, the second parameter is now reserved for an option object containing `{ locale, item, variant }`. If you previously passed a locale string directly, you can still do so, but using the options object is recommended for advanced selections.
 
 ---
 
 ## Useful links
 
 - [Compat Adapter Packages Guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/index.md)
-- [Dynamic Dictionaries - Collections, Variants & Dynamic Records](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dynamic_dictionaries/index.md)
+- [Dynamic Dictionaries - Collections & Variants](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dynamic_dictionaries/index.md)
 - [Configuration Reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intlayer/docs",
-  "version": "9.0.0-canary.7",
+  "version": "9.0.0-canary.8",
   "private": false,
   "description": "Intlayer documentation",
   "keywords": [
@@ -73,13 +73,13 @@
     "watch": "webpack --config ./webpack.config.ts --watch"
   },
   "dependencies": {
-    "@intlayer/config": "9.0.0-canary.7",
-    "@intlayer/core": "9.0.0-canary.7",
-    "@intlayer/types": "9.0.0-canary.7"
+    "@intlayer/config": "9.0.0-canary.8",
+    "@intlayer/core": "9.0.0-canary.8",
+    "@intlayer/types": "9.0.0-canary.8"
   },
   "devDependencies": {
-    "@intlayer/api": "9.0.0-canary.7",
-    "@intlayer/cli": "9.0.0-canary.7",
+    "@intlayer/api": "9.0.0-canary.8",
+    "@intlayer/cli": "9.0.0-canary.8",
     "@types/node": "25.9.4",
     "@utils/ts-config": "1.0.4",
     "@utils/ts-config-types": "1.0.4",

package/src/generated/docs.entry.ts

@@ -1373,26 +1373,6 @@ export const docsEntry = {
     vi: readLocale('dynamic_dictionaries/collections.md', 'vi'),
     uk: readLocale('dynamic_dictionaries/collections.md', 'uk'),
   } as unknown as Record<LocalesValues, Promise<string>>,
-  './docs/en/dynamic_dictionaries/dynamic_content.md': {
-    en: readLocale('dynamic_dictionaries/dynamic_content.md', 'en'),
-    ru: readLocale('dynamic_dictionaries/dynamic_content.md', 'ru'),
-    ja: readLocale('dynamic_dictionaries/dynamic_content.md', 'ja'),
-    fr: readLocale('dynamic_dictionaries/dynamic_content.md', 'fr'),
-    ko: readLocale('dynamic_dictionaries/dynamic_content.md', 'ko'),
-    zh: readLocale('dynamic_dictionaries/dynamic_content.md', 'zh'),
-    es: readLocale('dynamic_dictionaries/dynamic_content.md', 'es'),
-    de: readLocale('dynamic_dictionaries/dynamic_content.md', 'de'),
-    ar: readLocale('dynamic_dictionaries/dynamic_content.md', 'ar'),
-    it: readLocale('dynamic_dictionaries/dynamic_content.md', 'it'),
-    'en-GB': readLocale('dynamic_dictionaries/dynamic_content.md', 'en-GB'),
-    pt: readLocale('dynamic_dictionaries/dynamic_content.md', 'pt'),
-    hi: readLocale('dynamic_dictionaries/dynamic_content.md', 'hi'),
-    tr: readLocale('dynamic_dictionaries/dynamic_content.md', 'tr'),
-    pl: readLocale('dynamic_dictionaries/dynamic_content.md', 'pl'),
-    id: readLocale('dynamic_dictionaries/dynamic_content.md', 'id'),
-    vi: readLocale('dynamic_dictionaries/dynamic_content.md', 'vi'),
-    uk: readLocale('dynamic_dictionaries/dynamic_content.md', 'uk'),
-  } as unknown as Record<LocalesValues, Promise<string>>,
   './docs/en/dynamic_dictionaries/index.md': {
     en: readLocale('dynamic_dictionaries/index.md', 'en'),
     ru: readLocale('dynamic_dictionaries/index.md', 'ru'),