@intlayer/docs 9.3.3 → 9.4.0

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

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-08-06
+updatedAt: 2026-08-22
 title: 配置
 description: 了解如何为您的应用程序配置 Intlayer。了解可用于根据您的需求自定义 Intlayer 的各种设置和选项。
 keywords:
@@ -14,6 +14,9 @@ slugs:
   - concept
   - configuration
 history:
+  - version: 9.3.3
+    date: 2026-08-22
+    changes: "安装 `@intlayer/analytics` 后默认启用分析功能"
   - version: 9.1.3
     date: 2026-08-06
     changes: "将 `routing.enableProxy` 改为三态：未设置（auto）、`true`、`false`"
@@ -379,8 +382,8 @@ const config: IntlayerConfig = {
   analytics: {
     /**
      * 是否启用分析数据收集（页面浏览量、内容曝光、A/B 事件）。
-     * 需要设置 `editor.clientId` 以进行归因。
-     * 默认值：false
+     * 需要安装 `@intlayer/analytics` 并设置 `editor.clientId` 以进行归因。
+     * 默认值：true
      */
     enabled: true,
 
@@ -729,19 +732,17 @@ export default config;
 | `liveSyncPort`               | Live Sync 服务器的端口。                                                                                                         | `number`                          | `4000`                              | `4000`                                                                                          |                                                                                                                                                 |
 | `liveSyncURL`                | Live Sync 服务器的 URL。                                                                                                         | `string`                          | `'http://localhost:{liveSyncPort}'` | `'https://example.com'`                                                                         | 默认指向本地主机；可以更改为指向远程实时同步服务器。                                                                                            |
 
----
-
 ### 分析配置 (Analytics)
 
 定义与 Intlayer 分析相关的设置：收集实际展示给用户的内容（页面浏览量、内容曝光），并支持内容的 A/B 测试。
 
-分析功能严格采用选择加入（opt-in）模式：除非将 `analytics.enabled` 显式设置为 `true` **并且** 配置了用于归因的项目密钥（`editor.clientId`），否则不会收集任何数据。禁用时（默认），整个分析集成会从应用程序打包结果中被移除（死代码消除）。
+分析功能采用选择退出（opt-out）模式：默认启用，只要安装了 `@intlayer/analytics` 包**并且**配置了用于归因的项目密钥（`editor.clientId`），即开始收集数据。将 `analytics.enabled` 设为 `false`（或不安装该包），整个分析集成就会从应用程序打包结果中被移除（死代码消除）。
 
-| 字段            | 描述                                                   | 类型      | 默认值  | 示例    | 说明                                                                                          |
-| --------------- | ------------------------------------------------------ | --------- | ------- | ------- | --------------------------------------------------------------------------------------------- |
-| `enabled`       | 启用分析数据收集（页面浏览量、内容曝光、A/B 事件）。   | `boolean` | `false` | `true`  | 需要设置 `editor.clientId` 以进行归因；否则即使 `enabled` 为 `true`，分析功能仍保持禁用状态。 |
-| `flushInterval` | 自动批量发送到后端之间的毫秒数。                       | `number`  | `20000` | `10000` |                                                                                               |
-| `sampleRate`    | 要记录的会话比例，从 `0`（不记录）到 `1`（全部记录）。 | `number`  | `1`     | `0.5`   | 采样按会话确定性进行，因此被记录的会话会报告其所有事件（不会出现部分漏斗）。                  |
+| 字段            | 描述                                                   | 类型      | 默认值  | 示例    | 说明                                                                                                                       |
+| --------------- | ------------------------------------------------------ | --------- | ------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `enabled`       | 启用分析数据收集（页面浏览量、内容曝光、A/B 事件）。   | `boolean` | `true`  | `false` | 需要安装 `@intlayer/analytics` 并设置 `editor.clientId` 以进行归因；否则即使 `enabled` 为 `true`，分析功能仍保持禁用状态。 |
+| `flushInterval` | 自动批量发送到后端之间的毫秒数。                       | `number`  | `20000` | `10000` |                                                                                                                            |
+| `sampleRate`    | 要记录的会话比例，从 `0`（不记录）到 `1`（全部记录）。 | `number`  | `1`     | `0.5`   | 采样按会话确定性进行，因此被记录的会话会报告其所有事件（不会出现部分漏斗）。                                               |
 
 ---
 
@@ -980,6 +981,13 @@ export default config;
 
 ### 字典配置 (Dictionary)
 
+控制字典操作的设置，包括自动填充行为和内容生成。
+
+这个字典配置有两个主要目的：
+
+1. **默认值**: 在创建内容声明文件时定义默认值
+2. **回退行为**: 在未定义特定字段时提供回退值，允许您全局定义字典操作行为
+
 控制字典操作的参数，包括自动填充行为和内容生成。
 
 | 字段                        | 说明                                                                                         | 类型                                                                                                            | 默认值       | 示例                                                                                        | 备注                                                                                                                                                                                                                                                                                                        |
@@ -1021,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 密钥。
@@ -1062,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 如何优化和编译应用程序国际化的参数。
@@ -1101,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>`边界中。