Creation:2025-09-22Last update:2025-09-23
将此文档参考到您的 AI 助手ChatGPTClaudeDeepSeekGoogle AI modeGeminiPerplexityMistralGrok
使用您最喜欢的AI助手总结文档，并引用此页面和AI提供商
此页面的内容已使用 AI 翻译。
查看英文原文的最新版本编辑此文档
如果您有改善此文档的想法，请随时通过在GitHub上提交拉取请求来贡献。
文档的 GitHub 链接Copy
复制文档 Markdown 到剪贴板
新版 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来获取作为类型的语言环境。
更多信息请参见实现细节。
新的路由模式以实现更大灵活性
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.tsexport 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'// 带自定义属性的 Cookiestorage: { type: 'cookie', name: 'custom-locale', domain: '.example.com', secure: true, sameSite: 'strict'}// 带自定义键的 localStoragestorage: { type: 'localStorage', name: 'custom-locale'}// 多种存储类型以实现冗余storage: ['cookie', 'localStorage']符合 GDPR 的配置示例
针对需要在功能性和 GDPR 合规之间取得平衡的生产应用：
typescript
复制代码
复制代码到剪贴板
typescript;// intlayer.config.tsexport 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 要求。
可视化编辑器：包体积减小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: [ // 多个大型章节 ] }};系统自动执行：
- 分析内容大小和结构
- 适当分块内容
- 并行处理各个块
- 验证并在需要时重试
- 重建完整文件
从 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: "", },};字典内容映射
显示表格的所有内容
在弹窗中打开表格以清晰地查看所有数据
| 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 的迁移说明。