@intlayer/docs 9.4.0-canary.0 → 9.4.1

package/docs/zh/analytics.md

@@ -123,17 +123,6 @@ export default config;
 
 卸载 `@intlayer/analytics` 与设置 `enabled: false` 效果相同。完整字段列表请参阅[配置参考](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)。
 
-## 框架支持
-
-Analytics 已连接到 `react-intlayer` 共享的 `IntlayerProvider` 中，因此今天只要使用该 provider 的任何地方都可以使用它：
-
-| 框架                                                     | 状态                                                                       |
-| -------------------------------------------------------- | -------------------------------------------------------------------------- |
-| React                                                    | ✅ 可用                                                                    |
-| Next.js (`next-intlayer`)                                | ✅ 可用 (通过 `react-intlayer`)                                            |
-| React Native / Expo (`react-native-intlayer`)            | ✅ 可用 (通过 `react-intlayer`)                                            |
-| Vue, Svelte, Angular, Solid, Preact, Lit, Astro, Vanilla | 🚧 计划中 — 相同的客户端，遵循 `@intlayer/editor` 推出模式的提供商级别绑定 |
-
 ## 使用方法
 
 ### 自动 Provider 级别跟踪
@@ -177,6 +166,34 @@ const CTAButton = () => {
 
 ### 在客户端解析变体
 
+  </Tab>
+</Tabs>
+
+权重是可选的 — 为每个变体传递一个权重来改变分割比例，例如 `useExperiment("homepage-hero", ["default", "black_friday"], [9, 1])`。
+
+子应用随后读取与之匹配的字典的 [Variant](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dynamic_dictionaries/variants.md)：
+
+```tsx fileName="HeroBanner.tsx"
+import { useIntlayer } from "react-intlayer";
+
+export const HeroBanner = ({ variant }: { variant: string }) => {
+  const { headline, cta } = useIntlayer("hero-banner", { variant });
+
+  return (
+    <section>
+      <h1>{headline}</h1>
+      <a>{cta}</a>
+    </section>
+  );
+};
+```
+
+> 在**子组件**中读取 variant 是使其在 React 之外工作的关键：在 Vue、Svelte、Solid 和 Angular 中，传递给 `useIntlayer` 的选择器在组件设置时被捕获，所以读取必须发生在仅在 variant 已知时才挂载的组件中。
+
+如果实验涵盖整个页面而不是单个字典，请将变体提升到提供者上——参见 [Ambient variant](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dynamic_dictionaries/variants.md#ambient-variant)。下面的每个 `useIntlayer` 都会针对它进行解析，无需更改调用站点。
+
+如果你需要在组件外部获取原始赋值，直接访问客户端：
+
 ```tsx fileName="useHeroVariant.ts" codeFormat="tsx"
 import { getGlobalAnalyticsClient } from "@intlayer/analytics/client";
 
@@ -187,6 +204,8 @@ const variant = client?.getVariant("homepage-hero", [
 ]);
 ```
 
+> `getVariant` 只进行分配——它不记录曝光。优先使用 `useExperiment()`，否则转化率将没有分母。
+
 ## 隐私与性能
 
 - **设计上匿名**：会话由轮换 ID 标识；后端永远只存储该 ID 的 **SHA-256 哈希值** —— 从不存储原始 ID，从不存储 IP 地址。
@@ -236,6 +255,8 @@ const cms = createIntlayerCMS();
 const { data: audience } = await analyticsEndpoint(cms).getAudience(30);
 ```
 
+> **仅限服务器端。** `createIntlayerCMS()` 使用 `clientId` + `clientSecret` 进行身份验证，secret 永远不会在浏览器中可用 — 如果此代码片段在浏览器中运行，它将发出未经身份验证的请求。请将其保留在路由处理程序、服务器操作或脚本中。
+
 ## 有用的链接
 
 - [动态字典 - 集合与变体 (Collections & Variants)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dynamic_dictionaries/index.md)

package/docs/zh/benchmark/tanstack.md

@@ -196,6 +196,8 @@ GitHub 星数是项目受欢迎程度、社区信任和长期相关性的有力
 
 在 TanStack Start 上我也遇到了响应性问题：切换语言环境时，我必须强制 Provider 重新渲染并订阅语言环境更改事件，切换后的加载才能正常进行。
 
+在 TanStack Start 上，我也遇到了响应性问题：当locale改变时，我必须强制提供者重新渲染并订阅locale-change事件，以便在另一种语言中加载时行为正确。
+
 **(use-intl)** (`use-intl@4.9.1`):
 
 `use-intl` 是 React 生态中最时髦的“intl”成员（与 `next-intl` 同系），常被 AI Agent 推荐，但在我看来，在性能优先的环境下这是错误的。入门相对简单，但在实践中，优化和限制泄漏的过程相当复杂。同样，结合动态加载 + 命名空间 + TypeScript 类型会极大降低开发速度。
@@ -208,6 +210,8 @@ GitHub 星数是项目受欢迎程度、社区信任和长期相关性的有力
 
 尽管如此，它与基于 `t('a.b.c')` 的技术栈有着相同的重大缺点：优化是可能的，但非常耗时，且大型项目容易陷入不良实践（命名空间 + 动态加载 + 类型）。
 
+该 package 特别重（~17.3kb，约为 `react-intlayer` 的 3.5 倍）。
+
 消息格式也不同：`use-intl` 使用 ICU MessageFormat，而 `i18next` 使用自己的格式--如果混合使用它们，会增加工具链或迁移的复杂度。
 
 **(Lingui)** (`@lingui/core@5.3.0`):
@@ -218,6 +222,8 @@ GitHub 星数是项目受欢迎程度、社区信任和长期相关性的有力
 
 `react-intl` 是来自 Format.js 团队的高性能实现。但 DX 依然繁琐：`const intl = useIntl()` + `intl.formatMessage({ id: "xx.xx" })` 增加了复杂度和额外的 JavaScript 开销，并将全局 i18n 实例绑定到了 React 树中的许多节点。
 
+该 package 也很重（~14.4kb，大约是 `react-intlayer` 的 3 倍）。
+
 ### 4 - 推荐方案
 
 在本次 TanStack Start 基准测试中，没有与 `next-translate`（Next.js 插件 + `getStaticProps`）直接对应的方案。对于那些确实想要 `t()` API 且拥有成熟生态的团队，`react-i18next` 和 `use-intl` 仍是“合理”的选择，但要做好投入大量时间进行优化以避免泄漏的准备。

package/docs/zh/cli/ci.md

@@ -128,6 +128,8 @@ bun x intlayer ci fill --verbose --mode complete
 
 ### 在 CI/CD 管道中使用
 
+运行 `intlayer init` 为你生成两个可立即使用的 GitHub Actions 工作流（参见下面的 [Scaffolded GitHub Actions](#scaffolded-github-actions)）。这个例子展示了在 monorepo 中使用 `ci` 命令的等效设置，其中凭证从 `INTLAYER_PROJECT_CREDENTIALS` 按项目注入。
+
 在您的 CI/CD 配置中（例如，GitHub Actions、GitLab CI），将 `INTLAYER_PROJECT_CREDENTIALS` 设置为密钥：
 
 ```yaml

package/docs/zh/cli/doc-review.md

@@ -91,7 +91,13 @@ bun x intlayer doc review
 
 - **`--log`**：仅记录模式。不使用 AI 进行翻译；而是记录需要关注的块（带有行号和内容），供基础语言环境和目标语言环境参考，以帮助另一个代理生成翻译。
 
-  > 示例：`npx intlayer doc review --log`
+2. **For `report` mode**: Log blocks requiring attention without using AI, noting line numbers and content for both source and target.
+
+> 示例: `npx intlayer doc review --mode report`
+
+> 示例：`npx intlayer doc review --log`
+
+无论采用哪种模式，运行都会以一份综合报告结束，该报告列出与其基础文档对齐的文档和仍有需要编辑的块的文档。
 
 **入口输出选项：**
 

package/docs/zh/cli/fill.md

@@ -39,14 +39,6 @@ bun x intlayer fill
 
 此命令会分析您的内容声明文件，查找潜在问题，例如缺失的翻译、结构不一致或类型不匹配。如果发现任何问题，**intlayer fill** 将建议或应用更新，以保持您的字典一致且完整。
 
-关键要点：
-
-- 将大型 JSON 文件拆分为块，以保持在 AI 模型的上下文窗口限制内。
-- 如果输出格式不正确，会重试翻译。
-- 结合应用程序和文件特定的上下文以提高翻译准确性。
-- 通过不覆盖现有翻译来保留它们。
-- 使用队列系统并行处理文件、块和语言环境以提高速度。
-
 ## 关键要点：
 
 - 将大型 JSON 文件分割成块，以保持在 AI 模型的上下文窗口限制内。

package/docs/zh/cli/index.md

@@ -127,6 +127,8 @@ Intlayer 接受多种配置文件格式：
 
 - **[Login](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/login.md)** - 在 Intlayer CMS 中进行身份验证并获取访问凭据
 
+> `intlayer login` 生成一个**访问密钥** (`clientId` / `clientSecret`)，每个需要凭证的命令都会使用它。该密钥是服务器端凭证，永远不会到达您的客户端 bundle — 请参阅[保持访问密钥安全](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/login.md#keeping-the-access-key-safe)。
+
 ### 核心命令
 
 - **[Build Dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/build.md)** - 从内容声明文件构建字典

package/docs/zh/cli/list_projects.md

@@ -52,8 +52,6 @@ bun x intlayer projects list
 
   > 示例：`npx intlayer projects list --base-dir /path/to/workspace`
 
-  > 示例：`npx intlayer projects list --base-dir /path/to/workspace`
-
 - **`--git-root`**：从 git 根目录开始搜索，而不是基目录。这对于在 monorepo 或 git 仓库中查找所有 Intlayer 项目很有用。
 
   > 示例：`npx intlayer projects list --git-root`

package/docs/zh/cli/login.md

@@ -118,6 +118,34 @@ INTLAYER_CLIENT_SECRET=your_client_secret
 }
 ```
 
+## 保持访问密钥安全
+
+`intlayer login` 颁发一个**访问密钥**：一个 `clientId` / `clientSecret` 对，每个需要凭证的命令（`push`、`pull`、`fill`、`configuration push`、`live` 等）都使用它来进行身份验证。
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+  },
+};
+
+export default config;
+```
+
+> **`clientSecret` 是一个服务器端凭证。** 它授予完整的项目范围 API 访问权限——读取和写入您的字典、项目和组织。将其保存在 `.env`（被 git 忽略）或您的 CI 密钥存储中，切勿在配置文件中直接内联。
+
+Intlayer 强制执行此操作，而不仅仅是记录它：
+
+- `clientSecret` **从您的 bundler 内联的配置中被删除**，因此无论您使用何种框架集成，它都无法到达浏览器包。它仅在服务器端、运行时从环境中读取。
+- `clientId` 不同：它是**公开的**项目密钥，可以安全地交付，并由 [`@intlayer/analytics`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/analytics.md#how-events-are-authenticated) 使用以获取短期的、仅供摄取的 token。
+
+注释掉 `clientId` 足以禁用每个需要凭证的行为——远程字典获取、CMS 访问、分析——即使环境变量仍然已定义。
+
+对于 CI 管道，推荐使用 [`ci` 命令](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/ci.md)，它在单次运行期间注入凭证，而不是持久化它们。
+
 ## 手动配置
 
 如果浏览器没有自动打开，您可以手动访问终端中显示的 URL。

package/docs/zh/cli/push.md

@@ -89,29 +89,14 @@ bun x intlayer dictionary push
 
   > 示例：`npx intlayer dictionary push --keep-locale-dictionary`
 
-**准备选项：**
-
-- **`--build`**：在推送之前构建字典以确保内容是最新的。true 将强制构建，false 将跳过构建，undefined 将允许使用构建缓存。
-
 **日志选项：**
 
 - **`--verbose`**：启用详细日志以便调试。（CLI 默认启用）
 
 **Git 选项：**
 
-- **`--git-diff`**：仅针对包含从基准（默认 `origin/main`）到当前分支（默认 `HEAD`）的更改的字典运行。
-- **`--git-diff-base`**：指定 git diff 的基准引用（默认 `origin/main`）。
-- **`--git-diff-current`**：指定 git diff 的当前引用（默认 `HEAD`）。
-- **`--uncommitted`**：包含未提交的更改。
-- **`--unpushed`**：包含未推送的更改。
-- **`--untracked`**：包含未跟踪的文件。
-
 - **`--build`**：在推送之前构建字典以确保内容是最新的。设置为 true 将强制构建，false 将跳过构建，undefined 将允许使用构建缓存。
 
-**日志选项：**
-
-- **`--verbose`**：启用详细日志以便调试。（CLI 默认启用）
-
 **Git 选项：**
 
 - **`--git-diff`**：仅对包含从基准分支（默认 `origin/main`）到当前分支（默认 `HEAD`）的更改的字典运行。

package/docs/zh/compiler.md

@@ -40,15 +40,23 @@ author: aymericzip
 
 ## 为什么使用 Intlayer 编译器？
 
+- **自动化**: 消除了手动将内容复制粘贴到字典中的需要。
+
+- **Speed**: 优化的内容提取，确保您的构建过程保持快速。
+
 - **自动化**：消除手动将内容复制粘贴到字典中的步骤。
 - **速度**：优化的内容提取，确保构建过程保持快速。
 - **开发者体验**：将内容声明保留在使用它们的位置，提高可维护性。
 - **实时更新**：支持热模块替换（HMR），在开发过程中即时反馈。
 
+- **Live Updates**: 支持 Hot Module Replacement (HMR)，在开发过程中提供即时反馈。
+
 请参阅[Compiler vs. Declarative i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/compiler_vs_declarative_i18n.md)博客文章，了解更深入的比较。
 
 ## 为什么不使用 Intlayer 编译器？
 
+编译器虽然提供了一个优秀的"开箱即用"的体验，但它也引入了一些你应该了解的权衡：
+
 虽然编译器提供了出色的"开箱即用"体验，但它也引入了一些您应该了解的权衡：
 
 - **启发式歧义**：编译器必须猜测什么是面向用户的内容，什么是应用程序逻辑（例如，`className="active"`、状态代码、产品 ID）。在复杂的代码库中，这可能导致误报或遗漏的字符串，需要手动注释和异常处理。
@@ -94,6 +102,8 @@ export default defineConfig({
 });
 ```
 
+> 独立的 `intlayerCompiler()` 插件仍然为高级设置导出。与 `intlayer()` 一起注册是安全的——编译器会自行去重并且只运行一次。
+
 See complete tutorial: [Intlayer Compiler with Vite+React](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_vite+react_compiler.md)
 
 #### 框架支持
@@ -104,6 +114,10 @@ Vite 插件会自动检测并处理不同的文件类型：
 - **Vue**：需要安装 `@intlayer/vue-compiler`。
 - **Svelte**：需要安装 `@intlayer/svelte-compiler`。
 
+- **Vue**: 需要 `@intlayer/vue-compiler`。
+
+- **Svelte**: 需要 `@intlayer/svelte-compiler`。
+
 请确保为你的框架安装了相应的编译器包：
 
 ```bash

package/docs/zh/configuration.md

@@ -732,8 +732,6 @@ export default config;
 | `liveSyncPort`               | Live Sync 服务器的端口。                                                                                                         | `number`                          | `4000`                              | `4000`                                                                                          |                                                                                                                                                 |
 | `liveSyncURL`                | Live Sync 服务器的 URL。                                                                                                         | `string`                          | `'http://localhost:{liveSyncPort}'` | `'https://example.com'`                                                                         | 默认指向本地主机；可以更改为指向远程实时同步服务器。                                                                                            |
 
----
-
 ### 分析配置 (Analytics)
 
 定义与 Intlayer 分析相关的设置：收集实际展示给用户的内容（页面浏览量、内容曝光），并支持内容的 A/B 测试。
@@ -983,6 +981,13 @@ export default config;
 
 ### 字典配置 (Dictionary)
 
+控制字典操作的设置，包括自动填充行为和内容生成。
+
+这个字典配置有两个主要目的：
+
+1. **默认值**: 在创建内容声明文件时定义默认值
+2. **回退行为**: 在未定义特定字段时提供回退值，允许您全局定义字典操作行为
+
 控制字典操作的参数，包括自动填充行为和内容生成。
 
 | 字段                        | 说明                                                                                         | 类型                                                                                                            | 默认值       | 示例                                                                                        | 备注                                                                                                                                                                                                                                                                                                        |
@@ -1024,8 +1029,6 @@ dictionary: {
 | `mode`   | 指示日志记录器模式。   | `'default'` &#124; <br/> `'verbose'` &#124; <br/> `'disabled'` | `'default'`     | `'verbose'`     | • `'verbose'`: 记录更多调试信息。<br/>• `'disabled'`: 完全禁用日志记录器。 |
 | `prefix` | 日志中所有消息的前缀。 | `string`                                                       | `'[intlayer] '` | `'[我的前缀] '` |                                                                            |
 
----
-
 ### AI 配置 (AI)
 
 控制 Intlayer AI 功能的设置，包括提供商、模型和 API 密钥。
@@ -1065,8 +1068,6 @@ Intlayer 支持多个 AI 提供商，以提供最大的灵活性。当前支持
 | `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 等）传递给模型。 |
 
----
-
 ### 构建配置 (Build)
 
 控制 Intlayer 如何优化和编译应用程序国际化的参数。
@@ -1104,8 +1105,6 @@ Intlayer 支持多个 AI 提供商，以提供最大的灵活性。当前支持
 | `noMetadata`          | 如果为 `true`，编译器会从输出中删除字典元数据（键、内容包装器）。                                                                                                                                                                                                             | `boolean`                                                                                                       | `false`     | `false` → `{"key":"my-key","content":{"key":"value"}}` <br/> `true` → `{"key":"value"}`                                                                  | • 对于 i18next 格式或 ICU MessageFormat JSON 输出非常有用。<br/>• 与 `loadJSON` 插件很好地配合。                                           |
 | `dictionaryKeyPrefix` | 字典键前缀                                                                                                                                                                                                                                                                    | `string`                                                                                                        | `''`        |                                                                                                                                                          | 为提取的字典键添加可选前缀                                                                                                                 |
 
----
-
 ### 自定义架构 (Custom Schemas)
 
 | 字段      | 说明                                    | 类型                        |

package/docs/zh/custom_domains.md

@@ -138,6 +138,31 @@ getMultilingualUrls("/about", { currentDomain: "intlayer.org" });
 
 这些绝对 URL 已准备好用于 SEO 的 `<link rel="alternate" hreflang="...">` 标签。
 
+## 类型推断
+
+`routing.domains` 被序列化到生成的模块扩展中，因此 `getLocalizedUrl` 和 `getLocalizedPath` 将它们的返回类型缩小到域路由区域设置解析到的确切 URL — 包括前缀抑制。
+
+```ts
+// routing: { mode: 'prefix-no-default', domains: { en: 'intlayer.org', zh: 'intlayer.zh' } }
+
+getLocalizedUrl("/about", "zh");
+//     ^? "https://intlayer.zh/about" | "/about"
+
+getLocalizedPath("/about", "zh");
+//     ^? "/about"   (永远不会是源，也没有 /zh/ 前缀)
+```
+
+URL 类型是函数可以返回的两个值的 **联合**：区域设置域上的绝对 URL，以及当渲染的页面已经存在于该域上时它返回的相对 URL。`getLocalizedPath` 没有这样的歧义 — 它永远不会发出源 — 所以它保持单个字面量。
+
+共享域的区域设置在类型中也保持它们的正常前缀：
+
+```ts
+getLocalizedUrl("/about", "fr");
+//     ^? "https://intlayer.org/fr/about" | "/fr/about"
+```
+
+> 更改 `routing.domains` 后重新生成类型（`npx intlayer build`，或任何开发服务器运行）— 缩小来自生成的 `__RoutingRegistry`，而不是来自配置文件本身。
+
 ## 代理行为
 
 ### Next.js
@@ -170,6 +195,8 @@ GET intlayer.zh/about
 
 `intlayerProxy` Vite 插件在开发期间应用相同的逻辑：
 
+> 从 Intlayer v9 开始，`intlayerProxy()` 已直接捆绑到 `intlayer()` 插件中，并通过 `routing.enableProxy` 选项默认启用（`true` 为默认值）。如下所示单独注册现已成为可选项 — 保留它是为了向后兼容性以及需要控制插件顺序的设置。设置 `routing.enableProxy: false` 以选择退出。请参阅 [v9 发布说明](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/releases/v9.md)。
+
 ```typescript fileName="vite.config.ts"
 import { defineConfig } from "vite";
 import { intlayer } from "vite-intlayer";

package/docs/zh/custom_url_rewrites.md

@@ -248,7 +248,7 @@ Intlayer 在内部将这些模式规范化为统一语法，允许复杂的路
 
 <Tabs group='framework'>
   <Tab label="Next.js" value="nextjs">
-  
+
     ```tsx
     'use client';
 
@@ -263,7 +263,7 @@ Intlayer 在内部将这些模式规范化为统一语法，允许复杂的路
   </Tab>
 
   <Tab label="React Router" value="reactrouter">
-  
+
     ```tsx
     'use client';
 
@@ -279,7 +279,7 @@ Intlayer 在内部将这些模式规范化为统一语法，允许复杂的路
   </Tab>
 
   <Tab label="Vue" value="vue">
-  
+
     ```vue
     <script setup>
     import { useRewriteURL } from "vue-intlayer";
@@ -291,7 +291,7 @@ Intlayer 在内部将这些模式规范化为统一语法，允许复杂的路
 
   </Tab>
   <Tab label="Solid" value="solid">
-  
+
     ```tsx
     import { useRewriteURL } from "solid-intlayer";
 
@@ -303,7 +303,7 @@ Intlayer 在内部将这些模式规范化为统一语法，允许复杂的路
 
   </Tab>
   <Tab label="Svelte" value="svelte">
-  
+
     ```svelte
     <script>
     import { useRewriteURL } from "svelte-intlayer";
@@ -340,6 +340,8 @@ export function middleware(request: NextRequest) {
 
 对于 SolidJS、Vue 和 Svelte，`intlayerProxy` Vite 插件在开发期间管理重写。
 
+> 自 Intlayer v9 起，`intlayerProxy()` 已直接捆绑到 `intlayer()` 插件中，并通过 `routing.enableProxy` 选项默认启用（默认为 `true`）。如下所示单独注册现在是可选的 — 它保留用于向后兼容性和需要控制插件顺序的设置。设置 `routing.enableProxy: false` 来禁用。查看 [v9 发布说明](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/releases/v9.md)。
+
 ```typescript fileName="vite.config.ts"
 import { defineConfig } from "vite";
 import { intlayer } from "vite-intlayer";

package/docs/zh/dictionary/content_file.md

@@ -650,16 +650,6 @@ pluralContent: plural({
 });
 ```
 
-> 请参阅 [Plural Content 文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/plural.md) 以获取更多信息。### 插入内容 (`insert`)
-
-可以插入到其他内容中的内容：
-
-```typescript
-import { insert } from "intlayer";
-
-insertionContent: insert("这段文本可以插入到任何地方");
-```
-
 > 请参阅 [插入内容 (`insert`) 文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/insertion.md) 以获取更多信息。
 
 ### 插入内容 (`insert`)

package/docs/zh/dictionary/html.md

@@ -245,7 +245,7 @@ const myContent = html(
 
 <Tabs group="framework">
   <Tab label="React / Next.js" value="react">
-  
+
     ```tsx fileName="AppProvider.tsx"
     import { HTMLProvider } from "react-intlayer/html";
 
@@ -282,7 +282,7 @@ const myContent = html(
 
   </Tab>
   <Tab label="Vue" value="vue">
-  
+
     ```typescript fileName="main.ts"
     import { createApp, h } from "vue";
     import { intlayer } from "vue-intlayer";
@@ -327,7 +327,7 @@ const myContent = html(
 
   </Tab>
   <Tab label="Svelte" value="svelte">
-   
+
     ```svelte fileName="App.svelte"
     <script lang="ts">
       import { HTMLProvider } from "svelte-intlayer/html";
@@ -364,7 +364,7 @@ const myContent = html(
 
   </Tab>
   <Tab label="Preact" value="preact">
-   
+
     ```tsx fileName="AppProvider.tsx"
     import { HTMLProvider } from "preact-intlayer/html";
 
@@ -400,7 +400,7 @@ const myContent = html(
 
   </Tab>
   <Tab label="Solid" value="solid">
-   
+
     ```tsx fileName="AppProvider.tsx"
     import { HTMLProvider } from "solid-intlayer/html";
 
@@ -483,7 +483,9 @@ const myContent = html(
 <Tabs group="framework">
   <Tab label="React / Next.js" value="react">
     #### `<HTMLRenderer />` 组件
-    
+
+使用特定组件渲染 HTML 字符串。
+
     ```tsx
     import { HTMLRenderer } from "react-intlayer/html";
 
@@ -517,9 +519,9 @@ const myContent = html(
 
   </Tab>
   <Tab label="Vue" value="vue">
-   
+
     #### `<HTMLRenderer />` 组件
-   
+
     ```vue
     <script setup>
     import { HTMLRenderer } from "vue-intlayer/html";
@@ -532,9 +534,9 @@ const myContent = html(
 
   </Tab>
   <Tab label="Svelte" value="svelte">
-  
+
     #### `<HTMLRenderer />` 组件
-   
+
     ```svelte
     <script lang="ts">
     import { HTMLRenderer } from "svelte-intlayer/html";
@@ -566,9 +568,9 @@ const myContent = html(
 
   </Tab>
   <Tab label="Preact" value="preact">
-   
+
     #### `<HTMLRenderer />` 组件
-   
+
     ```tsx
     import { HTMLRenderer } from "preact-intlayer/html";
 
@@ -597,9 +599,9 @@ const myContent = html(
 
   </Tab>
   <Tab label="Solid" value="solid">
-   
+
     #### `<HTMLRenderer />` 组件
-   
+
     ```tsx
     import { HTMLRenderer } from "solid-intlayer/html";
 

package/docs/zh/dictionary/markdown.md

@@ -492,7 +492,7 @@ Markdown 渲染支持 **MDX** — 在您的 Markdown 中直接按名称使用任
 
 <Tabs group="framework">
   <Tab label="React" value="react">
-  
+
     #### `<MarkdownRenderer />` 组件
 
     使用特定选项渲染 Markdown 字符串。
@@ -531,7 +531,7 @@ Markdown 渲染支持 **MDX** — 在您的 Markdown 中直接按名称使用任
 
   </Tab>
   <Tab label="Next.js" value="nextjs">
-  
+
     #### `<MarkdownRenderer />` 组件
 
     使用特定选项渲染 Markdown 字符串。
@@ -957,6 +957,10 @@ Markdown 渲染支持 **MDX** — 在您的 Markdown 中直接按名称使用任
   </Tab>
   <Tab label="Angular" value="angular">
 
+> 支持 MDX — 任何在 Markdown 中使用的组件名称（例如 `<MyCustomJSXComponent />`）都会根据 `components` map 进行解析。
+
+你也可以使用自己的 markdown 渲染器：
+
     ```typescript fileName="app.module.ts"
     import { NgModule } from '@angular/core';
     import { IntlayerMarkdownModule } from 'angular-intlayer/markdown';
@@ -1047,7 +1051,7 @@ const MyComponent = () => {
 ```
 
   </Tab>
- 
+
   <Tab label="Vue" value="vue">
 
 Vue内置了`<Suspense>`组件。将渲染Markdown内容的组件包装在`<Suspense>`边界中。