从 i18next 迁移到 Intlayer

为什么从 i18next 迁移到 Intlayer?

迁移策略

从 i18next 迁移到 Intlayer 有两种互补策略：

1. 兼容性适配器（推荐用于现有应用） — 安装 @intlayer/i18next。这个包暴露了与 i18next 完全相同的 API，但在底层将所有翻译工作委托给 Intlayer。你可以保留现有的 i18next.t()、i18next.changeLanguage() 和 createInstance() 调用 — 唯一的改变是导入路径和初始化方式。

2. 完整迁移 — 逐步用原生 Intlayer 工具替换 i18next API，并在 .content.ts 文件中并置内容。

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

目录

快速迁移

以下步骤是使现有 i18next 应用以零代码更改运行在 Intlayer 上所需的最少要求。

1. 1

   安装依赖

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

   bash

   复制内容

   复制代码

   复制代码到剪贴板

   npx intlayer-cli init --interactive

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

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

   bash

   复制内容

   复制代码

   复制代码到剪贴板

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

   你可以保持 i18next 的安装 — 兼容性适配器将其用作 devDependency / peerDependency 来获取 TypeScript 类型。

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

   source 将语言环境映射到其 JSON 文件路径。location 告诉 Intlayer 监听器应监控哪个文件夹以获取更改。format: 'i18next' 选项确保正确解析占位符，如 {{name}}。

3. 3

   更新 Bundler 别名（可选）

   如果你使用 bundler（Vite、Webpack、esbuild），可以注入模块别名，使得 import ... from 'i18next' 自动解析为 @intlayer/i18next。这消除了手动更改代码库中任何导入的需要。

   对于 Vite：

   vite.config.ts

   复制内容

   复制代码

   复制代码到剪贴板

   import { defineConfig } from "vite";
   import i18nextVitePlugin from "@intlayer/i18next/plugin";
   
   export default defineConfig({
     plugins: [i18nextVitePlugin()],
   });

   i18nextVitePlugin() 包装 vite-intlayer 的 intlayer() 插件，并为你添加 i18next → @intlayer/i18next 别名。使用来自 vite-intlayer 的普通 intlayer() 插件会编译字典，但 不会 添加该别名 — 你需要手动将导入重命名为 @intlayer/i18next（见下一步）。

这就是快速迁移的全部内容。你的应用现在运行在 Intlayer 上，同时保持每个 i18next 导入和 API 完整。

完整迁移

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

1. 4

   显式导入重命名（可选）

   可选

   如果您想在源文件中明确声明依赖关系，或者您没有使用 bundler 插件来别名导入，您可以手动重命名导入：

   显示表格的所有内容

   显示表格的所有内容

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

   之前	之后
   import i18next from 'i18next'	import i18next from '@intlayer/i18next'
   import { createInstance } from 'i18next'	import { createInstance } from '@intlayer/i18next'
   import { t } from 'i18next'	import { t } from '@intlayer/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: ({ locale }) => `./src/locales/${locale}.json`,
         location: "src/locales",
       }),
     ],
     ai: {
       apiKey: process.env.OPENAI_API_KEY,
       // provider: "openai",     // 默认值
       // model: "gpt-4o-mini",   // 默认值
     },
   };
   
   export default config;

   查看 Intlayer CLI 文档 了解所有可用选项。

迁移后可以删除的内容

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

当您准备进一步操作时，Intlayer 自动发现您的 codebase 中任何地方的所有 .content.ts 和 .content.json 文件（默认情况下，在 ./src 内的任何地方）。您可以将 my-component.content.ts 文件放在逻辑代码的旁边，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