@intlayer/docs 9.3.0 → 9.3.2

package/docs/zh/configuration.md

@@ -403,7 +403,7 @@ const config: IntlayerConfig = {
   ai: {
     /**
      * 使用的 AI 提供商。
-     * 选项：'openai', 'anthropic', 'mistral', 'deepseek', 'gemini', 'ollama', 'openrouter', 'alibaba', 'fireworks', 'groq', 'huggingface', 'bedrock', 'googlevertex', 'togetherai', 'lmstudio'
+     * 选项：'openai', 'anthropic', 'mistral', 'deepseek', 'gemini', 'ollama', 'openrouter', 'alibaba', 'fireworks', 'groq', 'huggingface', 'bedrock', 'googlevertex', 'togetherai', 'lmstudio', 'moonshotai'
      * 默认值：'openai'
      */
     provider: "openai",
@@ -1034,15 +1034,15 @@ Intlayer 支持多个 AI 提供商，以提供最大的灵活性。当前支持
 - **Together.ai**
 - **LM Studio**
 
-| 字段                 | 说明                                                                                 | 类型                                                                                                                                                                                                                                                                                                                                                                                                                     | 默认值      | 示例                                                          | 备注                                                                                                                                              |
-| -------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `provider`           | 要为 Intlayer AI 功能使用的提供商。                                                  | `'openai'` &#124; <br/> `'anthropic'` &#124; <br/> `'mistral'` &#124; <br/> `'deepseek'` &#124; <br/> `'gemini'` &#124; <br/> `'ollama'` &#124; <br/> `'openrouter'` &#124; <br/> `'alibaba'` &#124; <br/> `'fireworks'` &#124; <br/> `'groq'` &#124; <br/> `'huggingface'` &#124; <br/> `'bedrock'` &#124; <br/> `'googleaistudio'` &#124; <br/> `'googlevertex'` &#124; <br/> `'togetherai'` &#124; <br/> `'lmstudio'` | `undefined` | `'anthropic'`                                                 | 不同的提供商需要不同的 API 密钥，且价格不同。                                                                                                     |
-| `model`              | 要为 AI 功能使用的 AI 模型。                                                         | `string`                                                                                                                                                                                                                                                                                                                                                                                                                 | 无          | `'gpt-4o-2024-11-20'`                                         | 具体模型取决于提供商。                                                                                                                            |
-| `temperature`        | 控制 AI 响应的随机性。                                                               | `number`                                                                                                                                                                                                                                                                                                                                                                                                                 | 无          | `0.1`                                                         | 温度越高 = 越具创造力且越不可靠。                                                                                                                 |
-| `apiKey`             | 所选提供商的您的 API 密钥。                                                          | `string`                                                                                                                                                                                                                                                                                                                                                                                                                 | 无          | `process.env.OPENAI_API_KEY`                                  | 应保持私密；使用环境变量。                                                                                                                        |
-| `applicationContext` | 有关应用程序的其他上下文，以帮助 AI 生成更准确的翻译（领域、目标受众、语气、术语）。 | `string`                                                                                                                                                                                                                                                                                                                                                                                                                 | 无          | `'我的自定义应用程序上下文'`                                  | 可用于添加规则（例如：`"您不应转换您的 URL"` ）。                                                                                                 |
-| `baseURL`            | AI API 的基础 URL。                                                                  | `string`                                                                                                                                                                                                                                                                                                                                                                                                                 | 无          | `'https://api.openai.com/v1'` <br/> `'http://localhost:5000'` | 可以指向本地或自定义的 AI API 端点。                                                                                                              |
-| `dataSerialization`  | AI 功能的数据序列化格式。                                                            | `'json'` &#124; <br/> `'toon'`                                                                                                                                                                                                                                                                                                                                                                                           | `undefined` | `'toon'`                                                      | • `'json'`: 默认，可靠；使用更多 token。<br/>• `'toon'`: token 更少，但也更不稳定。<br/>• 将上下文作为额外参数（reasoning effort 等）传递给模型。 |
+| 字段                 | 说明                                                                                 | 类型                                                                                                                                                                                                                                                                                                                                                                                                                                                 | 默认值      | 示例                                                          | 备注                                                                                                                                              |
+| -------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `provider`           | 要为 Intlayer AI 功能使用的提供商。                                                  | `'openai'` &#124; <br/> `'anthropic'` &#124; <br/> `'mistral'` &#124; <br/> `'deepseek'` &#124; <br/> `'gemini'` &#124; <br/> `'ollama'` &#124; <br/> `'openrouter'` &#124; <br/> `'alibaba'` &#124; <br/> `'fireworks'` &#124; <br/> `'groq'` &#124; <br/> `'huggingface'` &#124; <br/> `'bedrock'` &#124; <br/> `'googleaistudio'` &#124; <br/> `'googlevertex'` &#124; <br/> `'togetherai'` &#124; <br/> `'lmstudio'` &#124; <br/> `'moonshotai'` | `undefined` | `'anthropic'`                                                 | 不同的提供商需要不同的 API 密钥，且价格不同。                                                                                                     |
+| `model`              | 要为 AI 功能使用的 AI 模型。                                                         | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                             | 无          | `'gpt-4o-2024-11-20'`                                         | 具体模型取决于提供商。                                                                                                                            |
+| `temperature`        | 控制 AI 响应的随机性。                                                               | `number`                                                                                                                                                                                                                                                                                                                                                                                                                                             | 无          | `0.1`                                                         | 温度越高 = 越具创造力且越不可靠。                                                                                                                 |
+| `apiKey`             | 所选提供商的您的 API 密钥。                                                          | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                             | 无          | `process.env.OPENAI_API_KEY`                                  | 应保持私密；使用环境变量。                                                                                                                        |
+| `applicationContext` | 有关应用程序的其他上下文，以帮助 AI 生成更准确的翻译（领域、目标受众、语气、术语）。 | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                             | 无          | `'我的自定义应用程序上下文'`                                  | 可用于添加规则（例如：`"您不应转换您的 URL"` ）。                                                                                                 |
+| `baseURL`            | AI API 的基础 URL。                                                                  | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                             | 无          | `'https://api.openai.com/v1'` <br/> `'http://localhost:5000'` | 可以指向本地或自定义的 AI API 端点。                                                                                                              |
+| `dataSerialization`  | AI 功能的数据序列化格式。                                                            | `'json'` &#124; <br/> `'toon'`                                                                                                                                                                                                                                                                                                                                                                                                                       | `undefined` | `'toon'`                                                      | • `'json'`: 默认，可靠；使用更多 token。<br/>• `'toon'`: token 更少，但也更不稳定。<br/>• 将上下文作为额外参数（reasoning effort 等）传递给模型。 |
 
 ---
 

package/docs/zh/eslint.md

@@ -0,0 +1,336 @@
+---
+createdAt: 2026-08-12
+updatedAt: 2026-08-12
+title: ESLint 插件 | Intlayer 的 Lint 规则
+description: 使用 eslint-plugin-intlayer 捕获硬编码字符串、Intlayer 编译器无法优化的动态调用以及未使用的字典内容。支持 ESLint 和 oxlint，适用于 React、Vue、Svelte、Angular 和 Astro。
+keywords:
+  - Intlayer
+  - ESLint
+  - oxlint
+  - 代码检查
+  - i18n
+  - 国际化
+  - no-raw-text
+  - 硬编码字符串
+  - 未使用的翻译
+  - 死内容
+  - React
+  - Vue
+  - Svelte
+  - Angular
+slugs:
+  - doc
+  - eslint
+history:
+  - version: 9.3.1
+    date: 2026-08-12
+    changes: "初始化历史"
+author: aymericzip
+---
+
+# ESLint x OXLint 插件
+
+`eslint-plugin-intlayer` 能够捕获 TypeScript 无法发现的几类 i18n 错误：
+
+1. **硬编码文本**：从未写入字典中的文本。
+2. **动态调用**：能够通过类型检查并正常运行，但 Intlayer 编译器无法进行优化的调用。
+3. **死内容（Dead content）**：项目中没有任何地方读取的字典和字段（需手动开启）。
+
+未知的字典键、未知的字段路径和缺失的语言环境本身已是编译错误，因此插件不会重复报告它们。
+
+## 安装
+
+```bash packageManager="npm"
+npm install --save-dev eslint-plugin-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add --save-dev eslint-plugin-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add --dev eslint-plugin-intlayer
+```
+
+需要 ESLint 9 或更高版本（Flat config）。
+
+## 使用方法
+
+该插件可在 ESLint 和 [oxlint](https://oxc.rs) 中运行 — 拥有相同的规则和配置选项。
+
+<Tabs defaultTab="eslint">
+  <Tab label="ESLint" value="eslint">
+
+```javascript fileName="eslint.config.mjs" codeFormat="esm"
+import intlayer from "eslint-plugin-intlayer";
+
+export default [...intlayer.configs.recommended];
+```
+
+或者逐个启用规则：
+
+```javascript fileName="eslint.config.mjs" codeFormat="esm"
+import intlayer from "eslint-plugin-intlayer";
+
+export default [
+  {
+    plugins: { intlayer },
+    rules: {
+      "intlayer/no-raw-text": "warn",
+      "intlayer/static-dictionary-key": "error",
+      "intlayer/no-dynamic-field-access": "error",
+      "intlayer/enforce-adapter-import": "warn",
+      "intlayer/no-unused-content": "warn",
+    },
+  },
+];
+```
+
+  </Tab>
+  <Tab label="oxlint" value="oxlint">
+
+```json fileName=".oxlintrc.json"
+{
+  "jsPlugins": ["eslint-plugin-intlayer"],
+  "rules": {
+    "intlayer/no-raw-text": "warn",
+    "intlayer/static-dictionary-key": "error",
+    "intlayer/no-dynamic-field-access": "error",
+    "intlayer/enforce-adapter-import": "warn"
+  }
+}
+```
+
+两点注意事项：oxlint 对 JS 插件的支持仍处于 Alpha 阶段，且 oxlint 不支持自定义解析器 — 因此 `.vue`、`.svelte`、`.astro` 和 Angular 模板无法在此处进行 lint。请在 JS/TS/JSX 文件上运行 oxlint，其余文件保留使用 ESLint。
+
+上面特意排除了 `no-unused-content`：它需要从规则上下文中获取工作目录和被检查文件的路径，而 Alpha 阶段的 JS 插件桥接层无法保证提供这些信息。请在 ESLint 下运行该规则。
+
+  </Tab>
+</Tabs>
+
+### 预设配置
+
+| 配置            | `no-raw-text`           | `static-dictionary-key` | `no-dynamic-field-access` | `enforce-adapter-import` | `no-unused-content` |
+| --------------- | ----------------------- | ----------------------- | ------------------------- | ------------------------ | ------------------- |
+| `recommended`   | warn                    | error                   | error                     | off                      | off                 |
+| `strict`        | error (+ 非 JSX 字面量) | error                   | error                     | error                    | off                 |
+| `contract-only` | off                     | error                   | error                     | off                      | off                 |
+
+`recommended` 特意将 `no-raw-text` 设为 `warn`：将其指向现有代码库会一次性暴露所有未翻译的字符串，这不应该在第一天就导致构建中断。
+
+`enforce-adapter-import` 默认关闭 — 如果需要请显式启用。
+
+`no-unused-content` 在所有配置中均默认关闭（包括 `strict`）。这是唯一一个需要读取 Intlayer 配置并从磁盘遍历源文件的规则，因此启用它应当是一项经过深思熟虑的选择，而非预设自动执行的行为。
+
+## 规则列表
+
+### `no-raw-text`
+
+报告未在字典中声明的面向用户的文本。它使用与 `intlayer extract` 相同的检测逻辑，因此品牌名称、CSS 类名和技术标识符都会被忽略。
+
+```jsx
+// ✗ 报告错误
+<h1>Welcome to our documentation</h1>
+<input placeholder="Enter your email address" />
+
+// ✓ 正常
+const { title } = useIntlayer("home");
+<h1>{title}</h1>
+```
+
+内容声明文件（`*.content.ts`, …）会被跳过。
+
+若要一次性修复整个文件，运行 `npx intlayer extract`，让编译器自动将字符串移入字典。
+
+**配置选项**
+
+```javascript fileName="eslint.config.mjs" codeFormat="esm"
+{
+  "intlayer/no-raw-text": [
+    "warn",
+    {
+      // 值为面向用户文本的属性列表。
+      // 默认值: title, placeholder, alt, aria-label, label
+      attributes: ["title", "placeholder", "alt", "aria-label", "label"],
+
+      // 内容绝非面向用户文本的元素列表。
+      // 默认值: code, pre, script, style
+      ignoreElements: ["code", "pre", "script", "style"],
+
+      // 绝不报告的文本正则表达式。
+      ignorePatterns: ["^Powered by"],
+
+      // 是否同时报告标记语言之外的字符串字面量。默认值: false
+      includeStringLiterals: false,
+    },
+  ],
+}
+```
+
+### `static-dictionary-key`
+
+要求字典键必须是字符串字面量。
+
+编译器只有在调用位置直接读取到键时，才能预加载字典。使用计算键会静默跳过优化，转而打包所有字典。
+
+```typescript
+// ✗ 报告错误
+useIntlayer(dictionaryKey);
+useIntlayer(`home-${suffix}`);
+getTranslations({ namespace: page });
+
+// ✗ 变量仍然不是字面量
+const key = "home";
+useIntlayer(key);
+
+// ✓ 正常
+useIntlayer("home");
+getTranslations({ namespace: "home" });
+```
+
+这适用于 `useIntlayer`、`getIntlayer` 以及所有兼容适配器（`useTranslation`、`useTranslations`、`formatMessage`、`<FormattedMessage id>`、`<Trans i18nKey>` 等）。
+
+### `no-dynamic-field-access`
+
+要求从字典中读取的字段必须是静态已知的。
+
+编译器会移除它未检测到使用的字段。动态计算访问对其不可见，因此该读取在运行时可能会返回 `undefined`。
+
+```typescript
+// ✗ 报告错误
+const content = useIntlayer("home");
+content[fieldName];
+
+const t = useTranslations("home");
+t(messageKey);
+
+// ✓ 正常
+content.title;
+content["title"];
+content.items[0];
+t("hero.title");
+```
+
+### `enforce-adapter-import`
+
+优先使用 `@intlayer/*` 兼容适配器而非原始包。原始包仅在配置了打包工具别名时才会解析为 Intlayer；而适配器始终生效。可通过 `--fix` 自动修复。
+
+```typescript
+// ✗ 报告错误
+import { useTranslation } from "react-i18next";
+import { getTranslations } from "next-intl/server";
+
+// ✓ 正常
+import { useTranslation } from "@intlayer/react-i18next";
+import { getTranslations } from "@intlayer/next-intl/server";
+```
+
+### `no-unused-content`
+
+**默认关闭。** 报告项目中没有任何地方读取的内容，以及在多个位置声明的字典键。
+
+```typescript fileName="src/home.content.ts"
+export default {
+  key: "home", // ✗ 当项目中没有任何调用方请求 "home" 时报告
+  content: {
+    title: t({ zh: "标题", en: "Title" }),
+
+    // ✗ 当没有任何地方读取 `hero` 时报告
+    hero: {
+      subtitle: t({ zh: "副标题", en: "Subtitle" }),
+    },
+  },
+};
+```
+
+与其他规则不同，此规则无法仅凭眼前的文件给出判断 — 字段是否未使用仅相对于整个项目而言。在一次 lint 运行的首次内容声明时，它会加载你的 Intlayer 配置，匹配该配置声明的源文件（`build.traversePattern`、`compiler.transformPattern`），并运行驱动 `@intlayer/lsp` 和 VS Code 扩展中“未使用”删除线的同一套使用情况分析器。结果会缓存 `cacheTtl` 毫秒，因此每次运行只会扫描一次，而不是每个文件扫描一次。
+
+**配置选项**
+
+```javascript fileName="eslint.config.mjs" codeFormat="esm"
+{
+  "intlayer/no-unused-content": [
+    "warn",
+    {
+      // 报告没有任何地方引用的字典键。默认值: true
+      reportUnusedDictionaries: true,
+
+      // 报告没有任何地方读取的内容字段。默认值: true
+      reportUnusedFields: true,
+
+      // 报告在多处声明的重复键。默认值: true
+      reportDuplicateKeys: true,
+
+      // 绝不报告的字段路径正则表达式。
+      ignoreFields: ["^meta"],
+
+      // 扫描起始的项目根目录。默认值: ESLint 的工作目录
+      baseDir: process.cwd(),
+
+      // 项目扫描结果复用时长（毫秒）。默认值: 30000
+      cacheTtl: 30000,
+    },
+  ],
+}
+```
+
+如果你在长期运行的编辑器服务中进行 lint 且希望更快看到修改结果，可以降低 `cacheTtl`；当单次 lint 运行跨越 monorepo 中的多个 Intlayer 项目时，请设置 `baseDir`。
+
+> **倾向于保持沉默。** 此处的误报会导致翻译被误删，因此当字典以分析器无法跟踪的方式被使用时，不会报告任何内容：内容对象被整体传递、从中绑定的翻译函数（`const t = useTranslations("home")`）、通过直接导入访问的声明（`useDictionary(myDictionary)`）、来自另一个字典的 `nest()`、或者因 spread 展开而不详尽的字段列表。单文件组件（`.vue`、`.svelte`、`.astro`）计为使用了它们提及的字典中的所有字段，因为它们的脚本块在此处不会被解析。
+
+`reportDuplicateKeys` 读取构建时写入 `.intlayer/` 下的未合并字典，因此在项目至少构建过一次之前它会保持静默。共享一个键的两个声明会被合并，这是一种合法的模式 — 该报告之所以存在，是因为在两边同时定义的字段会静默保留两个值中的一个。
+
+分析器从以 ESM 形式分发的 `@intlayer/lsp` 中加载。因此该规则需要能够 `require()` ES 模块的 Node 版本 — Node 20.19+ 或 22.12+。在更低版本上，它不会报错中断 lint 运行，而是什么都不报告。
+
+## 框架支持
+
+每条规则均适用于所有 Intlayer 集成，包括 Vue、Svelte 和 Angular 模板内部。你只需告诉 ESLint 哪个解析器负责读取对应的文件类型即可。
+
+| 框架                      | 文件              | 解析器                            |
+| ------------------------- | ----------------- | --------------------------------- |
+| React, Preact, Solid, Lit | `.jsx` `.tsx`     | `typescript-eslint`               |
+| Next.js                   | `.jsx` `.tsx`     | `typescript-eslint`               |
+| Vue, Nuxt                 | `.vue`            | `vue-eslint-parser`               |
+| Svelte, SvelteKit         | `.svelte`         | `svelte-eslint-parser`            |
+| Angular                   | `.ts`             | `typescript-eslint`               |
+| Angular 模板              | `.component.html` | `@angular-eslint/template-parser` |
+| Astro                     | `.astro`          | `astro-eslint-parser`             |
+
+```javascript fileName="eslint.config.mjs" codeFormat="esm"
+import intlayer from "eslint-plugin-intlayer";
+import tseslint from "typescript-eslint";
+import vueParser from "vue-eslint-parser";
+import svelteParser from "svelte-eslint-parser";
+import angularTemplateParser from "@angular-eslint/template-parser";
+
+export default [
+  ...intlayer.configs.recommended,
+
+  {
+    files: ["**/*.{ts,tsx,jsx}"],
+    languageOptions: { parser: tseslint.parser },
+  },
+  {
+    files: ["**/*.vue"],
+    languageOptions: {
+      parser: vueParser,
+      parserOptions: { parser: tseslint.parser },
+    },
+  },
+  {
+    files: ["**/*.svelte"],
+    languageOptions: {
+      parser: svelteParser,
+      parserOptions: { parser: tseslint.parser },
+    },
+  },
+  {
+    files: ["**/*.component.html"],
+    languageOptions: { parser: angularTemplateParser },
+  },
+];
+```
+
+请仅安装项目所需的解析器。
+
+> **已知局限性。** 在 Vue 和 Angular 模板中，类似于 `{{ content[key] }}` 的表达式不会被 `no-dynamic-field-access` 检查。写在 script 块中的动态读取仍会被正常捕获。

package/docs/zh/interest_of_intlayer.md

@@ -188,7 +188,7 @@ export const ComponentExample = () => {
 这种方法允许你：
 
 1. **提高开发速度**
-   - 可以使用 VSCode 插件创建 `.content.{{ts|mjs|cjs|json}}` 文件
+   - 可以使用 VSCode 插件创建 `.content.{ts|js|mjs|cjs|json|tsx|jsx|md|mdx|yaml|yml}` 文件
    - IDE 中的 AI 自动补全工具（例如 GitHub Copilot）可以帮助你声明内容，减少复制/粘贴
 
 2. **保持代码库的整洁**
@@ -212,27 +212,27 @@ export const ComponentExample = () => {
 
 ## Intlayer 附加功能
 
-| 功能                                                                                                                      | 描述                                                                                                                                                                                                                                                                                                                                                      |
-| ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/frameworks.png?raw=true)                          | **跨框架支持**<br><br>Intlayer 兼容所有主流框架和库，包括 Next.js、React、Vite、Vue.js、Nuxt、Preact、Express 等。                                                                                                                                                                                                                                        |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/javascript_content_management.jpg?raw=true)       | **JavaScript 驱动的内容管理**<br><br>利用 JavaScript 的灵活性来高效地定义和管理你的内容。<br><br> - [内容声明](https://intlayer.org/doc/concept/content)                                                                                                                                                                                                  |
-| <img src="https://github.com/aymericzip/intlayer/blob/main/docs/assets/compiler.jpg?raw=true" alt="Feature" width="700">  | **编译器**<br><br>Intlayer 编译器可自动从组件中提取内容并生成字典文件。<br><br> - [编译器](https://intlayer.org/doc/compiler)                                                                                                                                                                                                                             |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/per_locale_content_declaration_file.png?raw=true) | **单语言内容声明文件**<br><br>在自动生成前，通过仅声明一次你的内容来加速开发。<br><br> - [单语言内容声明文件](https://intlayer.org/doc/concept/per-locale-file)                                                                                                                                                                                           |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true)                      | **类型安全环境**<br><br>利用 TypeScript 确保你的内容定义和代码没有错误，同时还能享受 IDE 的自动补全功能。<br><br> - [TypeScript 配置](https://intlayer.org/doc/environment/vite-and-react#configure-typescript)                                                                                                                                           |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/config_file.png?raw=true)                         | **简易配置**<br><br>仅需极简的配置即可快速启动并运行。轻松调整国际化、路由、AI、构建以及内容处理的设置。<br><br> - [探索 Next.js 集成](https://intlayer.org/doc/environment/nextjs)                                                                                                                                                                       |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/content_retrieval.png?raw=true)                   | **简化内容检索**<br><br>无需为每一小段内容调用 `t` 函数。使用单一的 hook 即可直接检索你的所有内容。<br><br> - [React 集成](https://intlayer.org/doc/environment/create-react-app)                                                                                                                                                                         |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/server_component.png?raw=true)                    | **一致的服务器组件实现**<br><br>完美适合 Next.js 服务器组件，客户端和服务器组件使用相同的实现，无需跨每个服务器组件传递你的 `t` 函数。<br><br> - [服务器组件](https://intlayer.org/doc/environment/nextjs#step-7-utilize-content-in-your-code)                                                                                                            |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/file_tree.png?raw=true)                           | **有条理的代码库**<br><br>保持代码库更有条理：1 组件 = 在同一文件夹下的 1 个字典。靠近其各自组件的翻译有助于提高可维护性和清晰度。<br><br> - [Intlayer 运行机制](https://intlayer.org/doc/concept/how-works-intlayer)                                                                                                                                     |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/url_routing.png?raw=true)                         | **增强的路由功能**<br><br>完全支持应用路由，无缝适应复杂的应用结构，适用于 Next.js、React、Vite、Vue.js 等。<br><br> - [探索 Next.js 集成](https://intlayer.org/doc/environment/nextjs)                                                                                                                                                                   |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/markdown.png?raw=true)                            | **Markdown 支持**<br><br>导入并解译本地文件以及远程 Markdown，以获得隐私政策、文档等多语言内容。解译并在你的代码中使 Markdown 元数据可被访问。<br><br> - [内容文件](https://intlayer.org/doc/concept/content/file)                                                                                                                                        |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/visual_editor.png?raw=true)                       | **免费的可视化编辑器与 CMS**<br><br>可视化编辑器和 CMS 免费向内容创作者开放，消除了对第三方本地化平台的依赖。使用 Git 保持内容同步，或使用 CMS 彻底或部分外置管理它。<br><br> - [Intlayer 编辑器](https://intlayer.org/doc/concept/editor) <br> - [Intlayer CMS](https://intlayer.org/doc/concept/cms)                                                    |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/bundle.png?raw=true)                              | **构建时摇树优化 (Tree-shakable) 内容**<br><br>构建时摇树优化内容，减小最终包的体积。按组件加载内容，并从打包体积中排除任何未使用的内容。支持懒加载以提高应用加载效率。<br><br> - [应用构建优化](https://intlayer.org/doc/concept/how-works-intlayer#app-build-optimization)                                                                              |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/static_rendering.png?raw=true)                    | **静态渲染**<br><br>不阻碍静态渲染（Static Rendering）。<br><br> - [Next.js 集成](https://intlayer.org/doc/environment/nextjs)                                                                                                                                                                                                                            |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/AI_translation.png?raw=true)                      | **AI 驱动翻译**<br><br>使用您自己的 AI 提供商/API 密钥，点击一下即可将您的网站翻译成 231 种语言，得益于 Intlayer 先进的 AI 翻译工具。<br><br> - [CI/CD 集成](https://intlayer.org/doc/concept/ci-cd) <br> - [Intlayer CLI](https://intlayer.org/doc/concept/cli) <br> - [自动填充](https://intlayer.org/doc/concept/auto-fill)                            |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/mcp.png?raw=true)                                 | **MCP 服务器集成**<br><br>提供用于 IDE 自动化的 MCP（Model Context Protocol）服务器，能够直接在你的开发环境中实现无缝的内容管理和 i18n 工作流。<br><br> - [MCP 服务器](https://github.com/aymericzip/intlayer/blob/main/docs/zh/mcp_server.md)                                                                                                            |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/vscode_extension.png?raw=true)                    | **VSCode 插件**<br><br>Intlayer 提供 VSCode 插件协助管理你的内容和翻译，构建你的字典，翻译你的内容等。<br><br> - [VSCode 插件](https://intlayer.org/doc/vs-code-extension)                                                                                                                                                                                |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/interoperability.png?raw=true)                    | **互操作性**<br><br>允许与 react-i18next、next-i18next、next-intl 和 react-intl 互操作。<br><br> - [Intlayer 与 react-intl](https://intlayer.org/blog/intlayer-with-react-intl) <br> - [Intlayer 与 next-intl](https://intlayer.org/blog/intlayer-with-next-intl) <br> - [Intlayer 与 next-i18next](https://intlayer.org/blog/intlayer-with-next-i18next) |
-| 测试缺失翻译 (CLI/CI)                                                                                                     | ✅ CLI: npx intlayer content test (对 CI 友好的审计)                                                                                                                                                                                                                                                                                                      |
+| 功能                                                                                                                      | 描述                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/frameworks.png?raw=true)                          | **跨框架支持**<br><br>Intlayer 兼容所有主流框架和库，包括 Next.js、React、Vite、Vue.js、Nuxt、Preact、Express 等。                                                                                                                                                                                                                                                                                                             |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/javascript_content_management.jpg?raw=true)       | **JavaScript 驱动的内容管理**<br><br>利用 JavaScript 的灵活性来高效地定义和管理你的内容。<br><br> - [内容声明](https://intlayer.org/doc/concept/content)                                                                                                                                                                                                                                                                       |
+| <img src="https://github.com/aymericzip/intlayer/blob/main/docs/assets/compiler.jpg?raw=true" alt="Feature" width="700">  | **编译器**<br><br>Intlayer 编译器可自动从组件中提取内容并生成字典文件。<br><br> - [编译器](https://intlayer.org/doc/compiler)                                                                                                                                                                                                                                                                                                  |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/per_locale_content_declaration_file.png?raw=true) | **单语言内容声明文件**<br><br>在自动生成前，通过仅声明一次你的内容来加速开发。<br><br> - [单语言内容声明文件](https://intlayer.org/doc/concept/per-locale-file)                                                                                                                                                                                                                                                                |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true)                      | **类型安全环境**<br><br>利用 TypeScript 确保你的内容定义和代码没有错误，同时还能享受 IDE 的自动补全功能。<br><br> - [TypeScript 配置](https://intlayer.org/doc/environment/vite-and-react#configure-typescript)                                                                                                                                                                                                                |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/config_file.png?raw=true)                         | **简易配置**<br><br>仅需极简的配置即可快速启动并运行。轻松调整国际化、路由、AI、构建以及内容处理的设置。<br><br> - [探索 Next.js 集成](https://intlayer.org/doc/environment/nextjs)                                                                                                                                                                                                                                            |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/content_retrieval.png?raw=true)                   | **简化内容检索**<br><br>无需为每一小段内容调用 `t` 函数。使用单一的 hook 即可直接检索你的所有内容。<br><br> - [React 集成](https://intlayer.org/doc/environment/create-react-app)                                                                                                                                                                                                                                              |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/server_component.png?raw=true)                    | **一致的服务器组件实现**<br><br>完美适合 Next.js 服务器组件，客户端和服务器组件使用相同的实现，无需跨每个服务器组件传递你的 `t` 函数。<br><br> - [服务器组件](https://intlayer.org/doc/environment/nextjs#step-7-utilize-content-in-your-code)                                                                                                                                                                                 |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/file_tree.png?raw=true)                           | **有条理的代码库**<br><br>保持代码库更有条理：1 组件 = 在同一文件夹下的 1 个字典。靠近其各自组件的翻译有助于提高可维护性和清晰度。<br><br> - [Intlayer 运行机制](https://intlayer.org/doc/concept/how-works-intlayer)                                                                                                                                                                                                          |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/url_routing.png?raw=true)                         | **增强的路由功能**<br><br>完全支持应用路由，无缝适应复杂的应用结构，适用于 Next.js、React、Vite、Vue.js 等。<br><br> - [探索 Next.js 集成](https://intlayer.org/doc/environment/nextjs)                                                                                                                                                                                                                                        |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/markdown.png?raw=true)                            | **Markdown 支持**<br><br>导入并解译本地文件以及远程 Markdown，以获得隐私政策、文档等多语言内容。解译并在你的代码中使 Markdown 元数据可被访问。<br><br> - [内容文件](https://intlayer.org/doc/concept/content/file)                                                                                                                                                                                                             |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/visual_editor.png?raw=true)                       | **免费的可视化编辑器与 CMS**<br><br>可视化编辑器和 CMS 免费向内容创作者开放，消除了对第三方本地化平台的依赖。使用 Git 保持内容同步，或使用 CMS 彻底或部分外置管理它。<br><br> - [Intlayer 编辑器](https://intlayer.org/doc/concept/editor) <br> - [Intlayer CMS](https://intlayer.org/doc/concept/cms)                                                                                                                         |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/bundle.png?raw=true)                              | **构建时摇树优化 (Tree-shakable) 内容**<br><br>构建时摇树优化内容，减小最终包的体积。按组件加载内容，并从打包体积中排除任何未使用的内容。支持懒加载以提高应用加载效率。<br><br> - [应用构建优化](https://intlayer.org/doc/concept/how-works-intlayer#app-build-optimization)                                                                                                                                                   |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/static_rendering.png?raw=true)                    | **静态渲染**<br><br>不阻碍静态渲染（Static Rendering）。<br><br> - [Next.js 集成](https://intlayer.org/doc/environment/nextjs)                                                                                                                                                                                                                                                                                                 |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/AI_translation.png?raw=true)                      | **AI 驱动翻译**<br><br>使用您自己的 AI 提供商/API 密钥，点击一下即可将您的网站翻译成 231 种语言，得益于 Intlayer 先进的 AI 翻译工具。<br><br> - [CI/CD 集成](https://intlayer.org/doc/concept/ci-cd) <br> - [Intlayer CLI](https://intlayer.org/doc/concept/cli) <br> - [自动填充](https://intlayer.org/doc/concept/auto-fill)                                                                                                 |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/mcp.png?raw=true)                                 | **MCP 服务器集成**<br><br>提供用于 IDE 自动化的 MCP（Model Context Protocol）服务器，能够直接在你的开发环境中实现无缝的内容管理和 i18n 工作流。<br><br> - [MCP 服务器](https://github.com/aymericzip/intlayer/blob/main/docs/zh/mcp_server.md)                                                                                                                                                                                 |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/vscode_extension.png?raw=true)                    | **VSCode 插件**<br><br>Intlayer 提供 VSCode 插件协助管理你的内容和翻译，构建你的字典，翻译你的内容等。<br><br> - [VSCode 插件](https://intlayer.org/doc/vs-code-extension)                                                                                                                                                                                                                                                     |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/interoperability.png?raw=true)                    | **互操作性**<br><br>允许与 react-i18next、next-i18next、next-intl 和 react-intl 互操作。<br><br> - [Intlayer 与 react-intl](https://intlayer.org/blog/intlayer-with-react-intl) <br> - [Intlayer 与 next-intl](https://intlayer.org/blog/intlayer-with-next-intl) <br> - [Intlayer 与 next-i18next](https://intlayer.org/blog/intlayer-with-next-i18next) <br> - [Intlayer 兼容适配器](https://intlayer.org/doc/compatibility) |
+| 测试缺失翻译 (CLI/CI)                                                                                                     | ✅ CLI: npx intlayer content test (对 CI 友好的审计)                                                                                                                                                                                                                                                                                                                                                                           |
 
 ## Intlayer 与其他解决方案的比较
 
@@ -271,3 +271,5 @@ GitHub Star 数是衡量项目受欢迎程度、社区信任度以及长期相
 `intlayer` 还可以帮助管理你的 `react-intl`、`react-i18next`、`next-intl`、`next-i18next` 以及 `vue-i18n` 命名空间。
 
 使用 `intlayer`，你可以声明你喜欢的 i18n 库格式的内容，并且 intlayer 将在你想指定的路径下生成命名空间（例如：`/messages/{{locale}}/{{namespace}}.json`）。
+
+如果你想继续使用当前 i18n 库的 API，`intlayer` 还提供了 **兼容适配器（compat adapters）**：这些包暴露与 `react-i18next`、`next-intl`、`react-intl`、`vue-i18n` 等完全相同的 API，但内容由 Intlayer 词典提供。这样你就可以逐步迁移，而无需重写代码。参见[兼容适配器文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/index.md)。

package/docs/zh/intlayer_with_create_react_app.md

@@ -612,6 +612,10 @@ export default App;
 - 根据语言环境调整 **文本方向** (`dir`)，提升不同阅读顺序语言的可读性和可用性。
 - 提供更 **无障碍** 的体验，因为辅助技术依赖这些属性以实现最佳功能。
 
+  </Step>
+
+</Steps>
+
 ### 配置 TypeScript
 
 Intlayer 使用模块增强来利用 TypeScript 的优势，使您的代码库更强大。

package/docs/zh/intlayer_with_lynx+react.md

@@ -67,6 +67,10 @@ Intlayer 不仅仅是一个 i18n 解决方案，还提供了一个**自托管的
 
 ---
 
+<Steps>
+
+<Step number={1} title="安装依赖">
+
 ### Packages
 
 - **intlayer**  

package/docs/zh/intlayer_with_nextjs_14.md

@@ -531,8 +531,6 @@ const ServerComponentExample: FC = () => {
 
 > 若要了解有关 `useIntlayer` 钩子的更多信息，请参阅[文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/next-intlayer/useIntlayer.md)。
 
-<Steps>
-
 </Step>
 
 <Step number={8} title="元数据的国际化">

package/docs/zh/intlayer_with_nextjs_15.md

@@ -433,8 +433,6 @@ export const ServerComponentExample: FC = () => {
 
 > 要了解有关 `useIntlayer` 钩子的更多信息，请参阅[文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/next-intlayer/useIntlayer.md)。
 
-<Steps>
-
 </Step>
 
 <Step number={7} title="配置中间件以检测语言环境">

package/docs/zh/intlayer_with_nextjs_page_router.md

@@ -514,8 +514,6 @@ const ComponentExample = () => {
 
 > 要了解有关 `useIntlayer` 钩子的更多信息，请参阅[文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/next-intlayer/useIntlayer.md)。
 
-<Steps>
-
 </Step>
 
 <Step number={8} title="元数据的国际化">

package/docs/zh/intlayer_with_nuxt.md

@@ -314,7 +314,7 @@ Intlayer 提供了多种 API 来访问您的内容：
   - 使用 `const content = useIntlayer("myContent");` 以及 `{{ content.myContent }}` / `<content.myContent />`。
   - 或者使用 `const { myContent } = useIntlayer("myContent");` 以及 `{{ myContent}}` / `<myContent/>` 来解构内容。
 
-<Steps>
+</Step>
 
 <Step number={6} title="更改内容语言">
 

package/docs/zh/intlayer_with_react_router_v7.md

@@ -198,6 +198,10 @@ export default config;
 
 > 通过此配置文件，您可以设置本地化的 URL、中间件重定向、cookie 名称、内容声明的位置和扩展名，禁用控制台中的 Intlayer 日志等。有关可用参数的完整列表，请参阅[配置文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)。
 
+<Steps>
+
+<Step number={5} title="创建根布局">
+
 #### 根布局
 
 ```tsx fileName="app/root.tsx"

package/docs/zh/intlayer_with_react_router_v7_fs_routes.md

@@ -131,6 +131,10 @@ export default config;
 
 > 通过此配置文件，您可以设置本地化的 URL、中间件重定向、cookie 名称、内容声明的位置和扩展名，禁用控制台中的 Intlayer 日志等。有关可用参数的完整列表，请参阅[配置文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)。
 
+<Steps>
+
+<Step number={5} title="创建根布局">
+
 #### 文件结构
 
 ```bash

package/docs/zh/intlayer_with_solid_start.md

@@ -572,7 +572,7 @@ export const Nav: Component = () => {
 
 <Step number={10} title="创建语言切换器组件">
 
-将切换器渲染为**真实的 <a> 锚点**而非 `<select>`：当前页面的每种语言都会变为可爬取的链接，并且可以在新标签页中打开，这是仅依靠 JavaScript 的控件无法提供的。
+将切换器渲染为**真实的 `<a>` 锚点**而非 `<select>`：当前页面的每种语言都会变为可爬取的链接，并且可以在新标签页中打开，这是仅依靠 JavaScript 的控件无法提供的。
 
 `getPathWithoutLocale` 会从当前路径中剥离语言段，而 `getLocalizedUrl` 会为目标语言重新构建它，因此这些链接会遵循你的路由模式，无需硬编码任何内容。导航是改变渲染语言的原因 —— `[[locale]]` 路由从 URL 中推导语言 —— 而 `setLocale` 会将选择保存在 `INTLAYER_LOCALE` cookie 中，以便以后访问无语言前缀的 URL 时能解析为相同的语言。
 

package/docs/zh/intlayer_with_svelte_kit.md

@@ -392,7 +392,7 @@ export const getLocale = (event: RequestEvent): Locale => {
 };
 ```
 
-> `getLocaleFromStorage` 将根据你的配置从 header 或 cookie 检查语言环境。有关更多详情，请参阅[配置](https://intlayer.org/doc/configuration)。
+> `getLocaleFromStorage` 将根据你的配置从 header 或 cookie 检查语言环境。有关更多详情，请参阅[配置](https://intlayer.org/doc/concept/configuration)。
 
 > `localeDetector` 函数将处理 `Accept-Language` header 并返回最佳匹配。