从 next-i18next 迁移到 Intlayer

为什么从 next-i18next 迁移到 Intlayer?

迁移策略

由于 next-i18next 在底层封装了 react-i18next 和 i18next，迁移到 Intlayer 有两种互补的策略：

1. 兼容适配器（推荐用于现有应用） — 安装 @intlayer/next-i18next、@intlayer/react-i18next 和 @intlayer/i18next。这些包公开的 API 完全相同，但在底层将所有翻译工作委托给 Intlayer。您可以保持现有的 useTranslation、appWithTranslation、serverSideTranslations 调用和 Next.js Pages 路由不变 — 唯一的变化是初始化。

2. 完全迁移 — 逐步使用原生 Intlayer 钩子（useIntlayer）替换 next-i18next API，并在组件旁边的 .content.ts 文件中并置内容。

本指南首先介绍策略 1（即插即用的兼容适配器），然后演示可选的完全迁移。

目录

快速迁移

以下步骤是让现有 Next.js Pages Router 应用在 Intlayer 上运行所需的最少要求,无需对页面和组件进行任何代码更改。

1. 1

   安装依赖

   安装 Intlayer 核心包和兼容适配器:

   bash

   复制内容

   复制代码

   复制代码到剪贴板

   npx intlayer-cli init --interactive

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

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

   bash

   复制内容

   复制代码

   复制代码到剪贴板

   npm install intlayer next-intlayer react-intlayer @intlayer/next-i18next @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin

   在迁移期间,您可以安全地保留 next-i18next、react-i18next 和 i18next 的安装,尽管在别名后您将删除它们。

2. 2

   配置 Intlayer

   intlayer init 命令创建一个启动器 intlayer.config.ts。更新它以匹配您现有的语言环境,并将 syncJSON 插件指向您的 next-i18next 消息文件(通常在 public/locales 内):

   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({
         // 匹配 i18next 占位符语法: {{name}}
         format: "i18next",
         source: ({ key, locale }) => `./public/locales/${locale}/${key}.json`,
         location: "public/locales",
       }),
     ],
   };
   
   export default config;

   source 将语言环境和命名空间(key)映射到其 JSON 文件路径。location 告诉 Intlayer 监听器监视哪个文件夹以获取更改。format: 'i18next' 选项确保正确解析 next-i18next 的占位符。

3. 3

   更新 Next.js 配置

   使用来自 @intlayer/next-i18next/plugin 的 createNextI18nPlugin 包装现有的 next.config.ts(或 .js)。此包装器组合 withIntlayer 并且 注入 next-i18next / react-i18next / i18next → @intlayer/* 别名,因此您现有的 import { useTranslation } from 'next-i18next' 调用在构建时透明地重定向。不需要更改源文件。

   next.config.ts

   复制内容

   复制代码

   复制代码到剪贴板

   import type { NextConfig } from "next";
   import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
   // 您可以删除从 next-i18next.config.js 导入的 i18n 配置
   // import { i18n } from './next-i18next.config';
   
   const withIntlayer = createNextI18nPlugin();
   
   const nextConfig: NextConfig = {
     // Intlayer 在底层管理 Next.js i18n 路由,
     // 所以您不再需要在这里传递 i18n 对象。
   };
   
   export default withIntlayer(nextConfig);

   您不再需要 next-i18next.config.js。 Intlayer 在构建时编译所有字典,无缝处理语言环境检测、路由和字典加载。

   倾向于使用来自 next-intlayer/server 的简单 withIntlayer? 它编译您的字典但不添加 next-i18next / react-i18next / i18next 别名 — 您随后需要手动将导入重命名为 @intlayer/*(请参阅第 4 步)。

快速迁移就到这里。您的 Next.js 应用现在在 Intlayer 上运行,同时保持每个 useTranslation、serverSideTranslations 和 appWithTranslation 调用完整。

有类型的翻译键 — 自动。 一旦 Intlayer 编译您的字典,useTranslation 和 getFixedT 就会针对您的实际内容进行类型化。键在您的 IDE 中自动完成,无效路径会在构建时导致 TypeScript 错误 — 无需额外设置。

tsx

复制内容

复制代码

复制代码到剪贴板

// Pages Router — 'about' 是一个已注册的字典键const { t } = useTranslation("about");t("counter.label"); // ✓ 自动完成t("does.not.exist"); // ✗ TypeScript 错误// getStaticProps / getServerSideProps (i18next 实例)const tAbout = i18n.getFixedT(null, "about");tAbout("counter.label"); // ✓ 有类型

完整迁移

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

1. 4

   显式导入重命名（可选）

   可选

   Intlayer 插件已经在 bundler 级别处理别名。如果您更希望在源文件中明确依赖关系，可以手动重命名导入：

   显示表格的所有内容

   显示表格的所有内容

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

   Before	After
   import { serverSideTranslations } from 'next-i18next/serverSideTranslations'	import { serverSideTranslations } from '@intlayer/next-i18next'
   import { appWithTranslation } from 'next-i18next'	import { appWithTranslation } from '@intlayer/next-i18next'
   import { useTranslation } from 'next-i18next'	import { useTranslation } from '@intlayer/next-i18next'
   import { useTranslation } from 'react-i18next'	import { useTranslation } from '@intlayer/react-i18next'

   这些是即插即用替代品——无需更改调用签名、参数或返回类型。

2. 5

   启用 AI 驱动的翻译自动化

   可选

   一旦 Intlayer 连接好，使用其 CLI 自动填充缺失的翻译：

   bash

   复制内容

   复制代码

   复制代码到剪贴板

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

   将 AI 配置添加到 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: "i18next",
         source: ({ key, locale }) => `./public/locales/${locale}/${key}.json`,
         location: "public/locales",
       }),
     ],
     ai: {
       apiKey: process.env.OPENAI_API_KEY,
       // provider: "openai",     // 默认值
       // model: "gpt-4o-mini",   // 默认值
     },
   };
   
   export default config;

   详见 Intlayer CLI 文档了解所有可用选项。

迁移后可以删除的内容

一旦 compat adapter 就位，以下 next-i18next 样板代码可以删除：

当你准备进一步操作时，Intlayer 会自动发现整个 codebase 中的所有 .content.ts 和 .content.json 文件（默认情况下，在 ./src 内的任何位置）。你可以将 my-component.content.ts 文件放在 MyComponent.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 (Pages Router) — Next.js 完整设置指南：intlayerwithnextjspagerouter.md