@intlayer/docs 7.0.0-canary.1 → 7.0.0-canary.3

package/docs/zh/releases/v7.md

@@ -0,0 +1,487 @@
+---
+createdAt: 2025-09-22
+updatedAt: 2025-09-23
+title: 新版 Intlayer v7 - 新特性介绍
+description: 了解 Intlayer v7 的新特性。性能、开发者体验的重大改进，以及增强国际化工作流程的新功能。
+keywords:
+  - Intlayer
+  - 本地化
+  - 开发
+  - 性能
+  - 开发者体验
+  - 功能
+  - React
+  - Next.js
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - releases
+  - v7
+---
+
+# 新版 Intlayer v7 - 新特性介绍
+
+欢迎使用 Intlayer v7！此次重大版本发布带来了性能、类型安全和开发者体验的显著提升。以下是主要亮点，包括迁移说明和实用示例。
+
+## 亮点
+
+- 缓存策略以加快构建速度
+- 改进的 TypeScript 类型生成，支持基于语言环境的类型
+- 包优化：语言环境使用字符串而非枚举
+- 新的路由模式：`prefix-no-default`、`prefix-all`、`no-prefix`、`search-params`
+- 符合 GDPR 的语言环境存储，默认使用 localStorage
+- 灵活的存储配置：支持 cookies、localStorage、sessionStorage 或多种组合
+- 视觉编辑器包体积缩小 30%
+- 增强的中间件配置选项
+- 更新的 fill 命令行为，提升内容管理
+- 通过完整内容声明文件更新增强稳定性
+- 智能重试管理，提升翻译准确性
+- 并行处理，加快翻译速度
+- 智能分块，处理大型文件以适应 AI 上下文限制
+
+---
+
+## 性能：缓存以加快构建速度
+
+v7 通过实现缓存策略来加快构建过程，而不是在每次构建时都使用 esbuild 重新构建内容声明。
+
+```bash
+npx intlayer build
+```
+
+新的缓存系统：
+
+- 存储已编译的内容声明以避免重复处理
+- 检测更改并仅重新构建修改过的文件
+- 显著减少大型项目的构建时间
+
+---
+
+## TypeScript：基于语言环境的类型生成
+
+TypeScript 类型现在按语言环境生成，提供更强的类型支持，消除了跨所有语言环境的联合类型。
+
+**v6 行为：**
+
+```tsx
+const content = getIntlayer("my-title-content", "en");
+// typeof content = { title: "My title" } | { title: "Mon titre" } | { title: "Mi título" }
+```
+
+**v7 行为：**
+
+```tsx
+const content = getIntlayer("my-title-content", "en");
+// typeof content = { title: "My title" }
+```
+
+优点：
+
+- 在您的 IDE 中提供更精确的自动完成
+- 更好的类型安全，避免跨语言环境的类型污染
+- 通过减少类型复杂性提升性能
+
+---
+
+## 包优化：将 Locales 作为字符串
+
+`Locales` 类型不再是枚举，这意味着它现在完全支持摇树优化，不会因为包含数千个未使用的语言环境记录而使您的包膨胀。
+
+**v6：**
+
+```typescript
+import { Locales } from "intlayer";
+// 包含所有语言环境的枚举 -> 不支持摇树优化
+
+const locale: Locales = Locales.ENGLISH;
+```
+
+**v7：**
+
+```typescript
+import { Locales, Locale } from "intlayer";
+// 字符串类型 -> 完全支持摇树优化
+
+const locale: Locale = Locales.ENGLISH;
+```
+
+> 因为 `Locales` 不再是枚举类型，所以你需要将类型从 `Locales` 改为 `Locale` 来获取作为类型的语言环境。
+
+更多信息请参见[实现细节](https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/types/src/index.ts)。
+
+---
+
+## 新的路由模式以实现更大灵活性
+
+v7 引入了统一的 `routing.mode` 配置，取代了之前的 `prefixDefault` 和 `noPrefix` 选项，提供了对 URL 结构更细粒度的控制。
+
+### 可用的路由模式
+
+- **`prefix-no-default`**（默认）：默认语言环境无前缀，其他语言环境有前缀
+  - `/dashboard`（英文）或 `/fr/dashboard`（法文）
+- **`prefix-all`**：所有语言环境都有前缀
+  - `/en/dashboard`（英文）或 `/fr/dashboard`（法文）
+- **`no-prefix`**：URL 中没有语言前缀（语言通过存储/请求头处理）
+  - 所有语言均为 `/dashboard`
+- **`search-params`**：语言作为查询参数传递
+  - `/dashboard?locale=en` 或 `/dashboard?locale=fr`
+
+### 基本配置
+
+```typescript
+// intlayer.config.ts
+export default {
+  internationalization: {
+    locales: ["en", "fr", "es"],
+    defaultLocale: "en",
+  },
+  routing: {
+    mode: "prefix-no-default", // 默认值
+  },
+};
+```
+
+---
+
+## GDPR 合规性：localStorage / cookies 存储
+
+v7 优先考虑用户隐私，默认使用 `localStorage` 作为存储机制，而非 cookies。此更改有助于避免因语言偏好设置而触发的 cookie 同意要求，从而更好地符合 GDPR 规定。
+
+### 存储配置选项
+
+新的 `routing.storage` 字段可用，作为之前 `middleware.cookieName` 和 `middleware.serverSetCookie` 选项的补充，提供灵活的存储配置：
+
+```typescript
+// 禁用存储
+storage: false
+
+// 简单存储类型
+storage: 'cookie'
+storage: 'localStorage'
+storage: 'sessionStorage'
+
+// 带自定义属性的 Cookie
+storage: {
+  type: 'cookie',
+  name: 'custom-locale',
+  domain: '.example.com',
+  secure: true,
+  sameSite: 'strict'
+}
+
+// 带自定义键的 localStorage
+storage: {
+  type: 'localStorage',
+  name: 'custom-locale'
+}
+
+// 多种存储类型以实现冗余
+storage: ['cookie', 'localStorage']
+```
+
+### 符合 GDPR 的配置示例
+
+针对需要在功能性和 GDPR 合规之间取得平衡的生产应用：
+
+```typescript
+typescript;
+// intlayer.config.ts
+export default {
+  internationalization: {
+    locales: ["en", "fr", "es"],
+    defaultLocale: "en",
+  },
+  routing: {
+    mode: "prefix-no-default",
+    storage: [
+      {
+        type: "localStorage", // 主要存储（无需同意）
+        name: "user-locale",
+      },
+      {
+        type: "cookie", // 可选的 Cookie 存储（需要同意）
+        name: "user-locale",
+        secure: true,
+        sameSite: "strict",
+        httpOnly: false,
+      },
+    ],
+  },
+};
+```
+
+### 启用 / 禁用 Cookie 存储
+
+使用 React / Next.js 的示例：
+
+可以全局定义：
+
+```typescript
+<IntlayerProvider isCookieEnabled={false}>
+  <App />
+</IntlayerProvider>
+```
+
+可以为每个 hook 本地覆盖：
+
+```ts
+const { setLocale } = useLocale({ isCookieEnabled: false });
+
+setLocale("en");
+```
+
+**注意：** Cookies 默认是启用的。
+**注意：** 请根据您的具体使用场景查看 [GDPR Cookie 要求](https://gdpr.eu/cookies/)。
+
+---
+
+## 可视化编辑器：包体积减小30%
+
+可视化编辑器包经过优化，比之前版本体积减少了30%，得益于：
+
+- 代码编辑器性能提升
+- 移除对 Intlayer 核心包的不必要依赖
+- 更好的摇树优化和模块打包
+
+这带来了更快的下载速度和更优的运行时性能。
+
+---
+
+## fill 命令：更新行为以更好地管理内容
+
+v7 引入了 `fill` 命令的改进行为，提供了更可预测和灵活的内容管理：
+
+### 新的 fill 行为
+
+- **`fill: true`** - 用所有语言的填充内容重写当前文件
+- **`fill: "path/to/file"`** - 填充指定文件而不修改当前文件
+- **`fill: false`** - 完全禁用自动填充
+
+### 对复杂内容结构的增强支持
+
+fill 命令现在支持复杂的内容声明结构，包括：
+
+- **组合对象**：引用其他对象的内容声明
+- **解构内容**：使用解构模式的内容
+- **嵌套引用**：对象在复杂层级中相互调用
+- **动态内容结构**：具有条件或计算属性的内容
+
+### 优势
+
+- **意图更明确**：行为现在更清晰地表明了哪些内容会被修改
+- **更好的分离**：内容文件可以与已填充的翻译文件分开保存
+- **改进的工作流程**：开发者可以更好地控制翻译存储的位置
+- **复杂结构支持**：处理具有多个相互关联对象的复杂内容架构
+
+### 示例用法
+
+```typescript
+// 使用所有语言重写当前文件
+const content = {
+  key: "example",
+  fill: true, // 重写此文件
+  content: {
+    title: "Hello World",
+  },
+};
+
+// 填充单独文件而不修改当前文件
+const content = {
+  key: "example",
+  fill: "./translations.json", // 创建/更新 translations.json
+  content: {
+    title: "Hello World",
+  },
+};
+
+// 禁用自动填充
+const content = {
+  key: "example",
+  fill: false, // 不自动填充
+  content: {
+    title: "Hello World",
+  },
+};
+
+// 复杂内容结构与组合对象
+const sharedContent = {
+  buttons: {
+    save: "保存",
+    cancel: "取消",
+  },
+};
+
+const content = {
+  key: "complex-example",
+  fill: true,
+  content: {
+    // 对其他对象的引用
+    sharedContent,
+
+    // 解构内容
+    ...sharedContent,
+
+    // 嵌套引用
+    sections: [
+      {
+        ...sharedContent.buttons,
+        header: "第1部分",
+      },
+    ],
+  },
+};
+```
+
+---
+
+## 增强的稳定性和翻译管理
+
+v7 引入了多项改进，使内容翻译更加可靠和高效：
+
+### 完整的内容声明文件更新
+
+系统现在更新 `.content.{ts,js,cjs,mjs}` 文件，而不是部分更新，确保：
+
+- **数据完整性**：完整的文件重写防止部分更新导致内容损坏
+- **一致性**：所有语言版本以原子方式更新，保持同步
+- **可靠性**：降低内容文件不完整或格式错误的风险
+
+### 智能重试管理
+
+新的重试机制防止以错误格式推送内容，并避免单个请求失败时破坏整个填充过程。
+
+### 并行处理以加快速度
+
+翻译操作现在在队列中运行，实现并行处理。这显著加快了处理速度。
+
+### 大文件的智能分块
+
+先进的分块策略处理大型内容文件，避免超出 AI 上下文窗口限制：
+
+### 示例工作流程
+
+```typescript
+// 大型内容文件自动进行分块
+const content = {
+  key: "large-documentation",
+  fill: true,
+  content: {
+    // 大型内容自动分块以供 AI 处理
+    introduction: "..." // 5000+ 字符
+    sections: [
+      // 多个大型章节
+    ]
+  }
+};
+```
+
+系统自动执行：
+
+1. 分析内容大小和结构
+2. 适当分块内容
+3. 并行处理各个块
+4. 验证并在需要时重试
+5. 重建完整文件
+
+---
+
+## 从 v6 版本迁移说明
+
+### 移除的配置项
+
+- **`middleware.cookieName`**：被 `routing.storage` 替代
+- **`middleware.serverSetCookie`**：被 `routing.storage` 替代
+- **`middleware.prefixDefault`**：被 `routing.mode` 替代
+- **`middleware.noPrefix`**：被 `routing.mode` 替代
+
+### 迁移映射
+
+#### 配置映射
+
+| v6 配置                    | v7 配置                                          |
+| -------------------------- | ------------------------------------------------ |
+| `autoFill: xxx`            | `fill: xxx`                                      |
+| `prefixDefault: false`     | `mode: 'prefix-no-default'`                      |
+| `prefixDefault: true`      | `mode: 'prefix-all'`                             |
+| `noPrefix: true`           | `mode: 'no-prefix'`                              |
+| `cookieName: 'my-locale'`  | `storage: { type: 'cookie', name: 'my-locale' }` |
+| `serverSetCookie: 'never'` | `storage: false` 或从存储数组中移除 cookie`      |
+
+#### 迁移示例
+
+**迁移前 (v6):**
+
+```typescript
+export default {
+  middleware: {
+    headerName: "x-intlayer-locale",
+    cookieName: "intlayer-locale",
+    prefixDefault: false,
+    basePath: "",
+    serverSetCookie: "always",
+    noPrefix: false,
+  },
+};
+```
+
+**升级后 (v7):**
+
+```typescript
+export default {
+  routing: {
+    mode: "prefix-no-default",
+    storage: "localStorage", // 如果需要使用 cookie 存储，可以改为 'cookie'
+    headerName: "x-intlayer-locale",
+    basePath: "",
+    detectLocaleOnPrefetchNoPrefix: false,
+  },
+};
+```
+
+#### 字典内容映射
+
+| v6 字典内容     | v7 字典内容 |
+| --------------- | ----------- |
+| `autoFill: xxx` | `fill: xxx` |
+
+#### 升级示例
+
+**升级前 (v6):**
+
+```typescript
+const content = {
+  key: "example",
+  autoFill: true, // 重写此文件
+  content: {
+    title: "你好，世界",
+  },
+};
+```
+
+**之后 (v7):**
+
+```typescript
+const content = {
+  key: "example",
+  fill: true, // 重写此文件
+  content: {
+    title: "你好，世界",
+  },
+};
+```
+
+---
+
+## 从 v5 到 v6 的迁移说明
+
+更多信息请查看 [从 v5 到 v6 的迁移说明](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/releases/v6.md)。
+
+---
+
+## 有用的链接
+
+- [配置参考](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)
+- [中间件文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/next-intlayer/index.md)
+- [TypeScript 类型](https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/types/src/index.ts)
+- [GDPR Cookie 指南](https://gdpr.eu/cookies/)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intlayer/docs",
-  "version": "7.0.0-canary.1",
+  "version": "7.0.0-canary.3",
   "private": false,
   "description": "Intlayer documentation",
   "keywords": [
@@ -69,17 +69,17 @@
     "watch": "webpack --config ./webpack.config.ts --watch"
   },
   "dependencies": {
-    "@intlayer/config": "workspace:*",
-    "@intlayer/core": "workspace:*",
-    "@intlayer/types": "workspace:*"
+    "@intlayer/config": "7.0.0-canary.3",
+    "@intlayer/core": "7.0.0-canary.3",
+    "@intlayer/types": "7.0.0-canary.3"
   },
   "devDependencies": {
-    "@intlayer/api": "workspace:*",
-    "@intlayer/cli": "workspace:*",
+    "@intlayer/api": "7.0.0-canary.3",
+    "@intlayer/cli": "7.0.0-canary.3",
     "@types/node": "24.9.1",
-    "@utils/ts-config": "workspace:*",
-    "@utils/ts-config-types": "workspace:*",
-    "@utils/tsdown-config": "workspace:*",
+    "@utils/ts-config": "7.0.0-canary.3",
+    "@utils/ts-config-types": "7.0.0-canary.3",
+    "@utils/tsdown-config": "7.0.0-canary.3",
     "fast-glob": "3.3.3",
     "rimraf": "6.0.1",
     "tsdown": "0.15.9",
@@ -87,11 +87,11 @@
     "vitest": "4.0.3"
   },
   "peerDependencies": {
-    "@intlayer/api": "workspace:*",
-    "@intlayer/cli": "workspace:*",
-    "@intlayer/config": "workspace:*",
-    "@intlayer/core": "workspace:*",
-    "@intlayer/types": "workspace:*"
+    "@intlayer/api": "7.0.0-canary.3",
+    "@intlayer/cli": "7.0.0-canary.3",
+    "@intlayer/config": "7.0.0-canary.3",
+    "@intlayer/core": "7.0.0-canary.3",
+    "@intlayer/types": "7.0.0-canary.3"
   },
   "engines": {
     "node": ">=14.18"

package/src/common.ts

@@ -68,6 +68,11 @@ export type FileMetadata = {
   author?: string;
   youtubeVideo?: string;
   applicationTemplate?: string;
+  history?: {
+    version: string;
+    date: string;
+    changes: string;
+  }[];
 };
 
 export const formatMetadata = (