从 next-intl 迁移到 Intlayer

为什么从 next-intl 迁移到 Intlayer？

迁移策略

现有应用的推荐方法是使用 compat adapter：安装 @intlayer/next-intl，它公开了与 next-intl 完全相同的 API，但在幕后将所有翻译工作委托给 Intlayer。

您可以保留现有的 useTranslations、getTranslations、NextIntlClientProvider 等 — 唯一的变化是导入路径。无需重构调用签名、属性形状或组件结构。

随着时间的推移，您可以选择将各个文件迁移到 Intlayer 更丰富的 .content.ts 格式，以解锁可视化编辑器、CMS 和按组件内容作用域的功能 — 但这一步完全是可选的，可以逐步进行。

目录

快速迁移

以下步骤是使现有 next-intl 应用在 Intlayer 上运行所需的最少要求，无需更改任何代码。

1. 1

   安装依赖

   安装 Intlayer 核心包和 @intlayer/next-intl 兼容性适配器：

   bash

   复制内容

   复制代码

   复制代码到剪贴板

   npx intlayer-cli init --interactive

   --interactive 标志是可选的。如果你是 AI 代理，请使用 intlayer-cli init。

   此命令将检测你的环境并安装所需的包。例如：

   bash

   复制内容

   复制代码

   复制代码到剪贴板

   npm install intlayer next-intlayer @intlayer/next-intl @intlayer/sync-json-plugin

   保持 next-intl 已安装 — 它仍然是 URL 路由（createNavigation、createMiddleware、Link、redirect、usePathname、useRouter）所必需的。兼容性适配器不替换路由层。

2. 2

   配置 Intlayer

   intlayer init 命令创建一个启动器 intlayer.config.ts。更新它以匹配你现有的语言，并将 syncJSON 插件指向你的消息文件：

   intlayer.config.ts

   复制内容

   复制代码

   复制代码到剪贴板

   import { Locales, type IntlayerConfig } from "intlayer";
   import { syncJSON } from "@intlayer/sync-json-plugin";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         // 在此处添加所有现有的语言
       ],
       defaultLocale: Locales.ENGLISH,
     },
     plugins: [
       syncJSON({
         // 'icu' 与 next-intl 的 ICU 占位符语法匹配：{name}、{count, plural, ...}
         format: "icu",
         source: ({ locale }) => `./messages/${locale}.json`,
         location: "messages",
       }),
     ],
   };
   
   export default config;

   source 将语言映射到其 JSON 文件路径。location 告诉 Intlayer 监视器要监视哪个文件夹以获取更改。format: 'icu' 选项确保正确解析 ICU 占位符，如 {name} 和 {count, plural, one {# item} other {# items}}。

   有关配置选项的完整列表，请参阅配置文档。

3. 3

   将 Intlayer 插件添加到 Next.js

   使用来自 @intlayer/next-intl/plugin 的 createNextIntlPlugin 包装你现有的 Next.js 配置。此包装器组合了 withIntlayer 并为你注册了 next-intl → @intlayer/next-intl 别名：

   next.config.ts

   复制内容

   复制代码

   复制代码到剪贴板

   import type { NextConfig } from "next";
   import { createNextIntlPlugin } from "@intlayer/next-intl/plugin";
   
   const withIntlayer = createNextIntlPlugin();
   
   const nextConfig: NextConfig = {
     /* 你现有的配置选项 */
   };
   
   export default withIntlayer(nextConfig);

   createNextIntlPlugin() 包装了 withIntlayer，自动检测 Webpack 或 Turbopack，连接内容监视、字典编译，以及——至关重要的——注入模块别名，使你现有的 import … from 'next-intl' 调用在构建时透明地重定向到 @intlayer/next-intl。路由条目 next-intl/routing 保持指向真实包。不需要源文件更改。

   更喜欢来自 next-intlayer/server 的普通 withIntlayer？它会编译你的字典，但它不添加 next-intl 别名——你随后需要手动将导入重命名为 @intlayer/next-intl（见步骤 4）。

   你不再需要 getRequestConfig 或 loadMessages。 使用 next-intl 时，你必须编写一个 src/i18n.ts 文件，通过 getRequestConfig 在每个请求上加载 JSON 消息包。Intlayer 在构建时编译所有字典，因此没有运行时加载步骤。你可以完全删除该文件（或如果你仍然使用 createNavigation，只保留路由部分）。

快速迁移就到这里。你的应用现在在 Intlayer 上运行，同时保持每个 next-intl 导入和 API 完整。

类型化翻译键——自动。 一旦 Intlayer 编译你的字典，useTranslations 和 getTranslations 就会根据你的实际内容进行类型化。键在你的 IDE 中自动完成，无效路径会在构建时导致 TypeScript 错误——不需要额外设置。

tsx

复制内容

复制代码

复制代码到剪贴板

// 客户端组件——'about' 是一个已注册的字典键const t = useTranslations("about");t("counter.label"); // ✓ 自动完成t("does.not.exist"); // ✗ TypeScript 错误// 服务器组件const t = await getTranslations("about");t("counter.label"); // ✓ 类型化

完整迁移

下面的步骤是可选的，可以逐步执行。它们解锁了 Intlayer 的完整功能集：可视化编辑器、CMS、类型化内容文件、AI 驱动的翻译等。

1. 4

   显式导入重命名（可选）

   可选

   createNextIntlPlugin() 包装器已在打包工具级别处理了 next-intl → @intlayer/next-intl 别名。如果你希望在源文件中明确依赖关系（并改用纯 withIntlayer 插件），可以手动重命名导入：

   显示表格的所有内容

   显示表格的所有内容

   在弹窗中打开表格以清晰地查看所有数据

   之前	之后
   import { useTranslations } from 'next-intl'	import { useTranslations } from '@intlayer/next-intl'
   import { useLocale } from 'next-intl'	import { useLocale } from '@intlayer/next-intl'
   import { NextIntlClientProvider } from 'next-intl'	import { NextIntlClientProvider } from '@intlayer/next-intl'
   import { getTranslations } from 'next-intl/server'	import { getTranslations } from '@intlayer/next-intl/server'
   import { getLocale } from 'next-intl/server'	import { getLocale } from '@intlayer/next-intl/server'
   import { setLocale } from 'next-intl/server'	import { setLocale } from '@intlayer/next-intl/server'
   import { getMessages } from 'next-intl/server'	import { getMessages } from '@intlayer/next-intl/server'

   始终从真实的 next-intl 保持路由导入 — compat 适配器不替换 URL 路由层：

   ts

   复制内容

   复制代码

   复制代码到剪贴板

   // ✅ 始终从真实的 'next-intl' 保持这些import { createNavigation } from "next-intl/routing";import { createMiddleware } from "next-intl/server";import { defineRouting } from "next-intl/routing";

   或者，你可以使用 @intlayer/next-intl/routing 中的 defineRouting，它会自动从你的 intlayer.config.ts 合并语言环境配置。

2. 5

   启用 AI 驱动的翻译自动化

   可选

   Intlayer 接入后，你可以使用其 CLI 使用你选择的 LLM 自动填充缺失的翻译：

   bash

   复制内容

   复制代码

   复制代码到剪贴板

   # 测试缺失的翻译（添加到 CI）npx intlayer test# 使用 AI 填充缺失的翻译npx intlayer fill

   将 OPENAI_API_KEY（或你首选提供商的密钥）添加到 .env 文件，然后扩展你的 intlayer.config.ts：

   intlayer.config.ts

   复制内容

   复制代码

   复制代码到剪贴板

   import { Locales, type IntlayerConfig } from "intlayer";
   import { syncJSON } from "@intlayer/sync-json-plugin";
   
   // 配置对象
   const config: IntlayerConfig = {
     internationalization: {
       locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
       defaultLocale: Locales.ENGLISH,
     },
     plugins: [
       syncJSON({
         format: "icu",
         source: ({ locale }) => `./messages/${locale}.json`,
         location: "messages",
       }),
     ],
     ai: {
       apiKey: process.env.OPENAI_API_KEY,
       // provider: "openai",     // 默认值
       // model: "gpt-4o-mini",   // 默认值
     },
   };
   
   export default config;

   有关所有可用选项，请参阅 Intlayer CLI 文档。

迁移后可以删除的内容

一旦 @intlayer/next-intl 就位，以下 next-intl 样板代码可以删除：

当你准备好进一步操作时，Intlayer 自动发现代码库中任何位置的所有 .content.ts 和 .content.json 文件（默认情况下，在 ./src 内的任何位置）。你可以将 about.content.ts 文件放在 about/page.tsx 文件旁边，Intlayer 将在构建时将其选中，无需额外配置 — 无需导入、无需注册、无需集中索引文件。这使得将翻译与页面和组件并置完全无摩擦。

配置 TypeScript

Intlayer 使用模块扩展来为您的翻译键提供完整的 TypeScript intellisense。确保您的 tsconfig.json 包含自动生成的类型：

{  // ... 您现有的 TypeScript 配置  "include": [    // ... 您现有的 TypeScript 配置    ".intlayer/**/*.ts", // 包含自动生成的类型  ],}

Git 配置

将 Intlayer 生成的目录添加到您的 .gitignore：

# Ignore the files generated by Intlayer.intlayer

进一步了解

• Visual Editor — 在浏览器中直观管理翻译: Intlayer Visual Editor
• CMS — 外部化和远程管理内容: Intlayer CMS
• VS Code Extension — 获得自动完成和实时翻译错误检测: Intlayer VS Code Extension
• CLI Reference — CLI 命令的完整列表: Intlayer CLI
• Intlayer with Next.js — Next.js 的完整设置指南: intlayerwithnextjs_16.md