从 @nuxtjs/i18n 迁移到 Intlayer

为什么从 @nuxtjs/i18n 迁移到 Intlayer？

迁移策略

由于 @nuxtjs/i18n 在底层由 vue-i18n 驱动，迁移到 Intlayer 有两种互补的策略：

1. 兼容适配器（推荐用于现有应用） — 安装 @intlayer/vue-i18n 和 nuxt-intlayer。这暴露了与 vue-i18n 完全相同的 API，但在底层将所有翻译工作委托给 Intlayer。您保持现有的 $t、useI18n() 和 Nuxt 路由不变 — 唯一的变化是初始化。

2. 完整迁移 — 逐步用本地 Intlayer hooks（useIntlayer）替换 @nuxtjs/i18n API，并在组件旁边的 .content.ts 文件中共同放置内容。

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

目录

快速迁移

以下步骤是使现有 Nuxt 应用在 Intlayer 上运行所需的最低要求，组件中无需任何代码更改。

1. 1

   安装依赖

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

   bash

   复制内容

   复制代码

   复制代码到剪贴板

   npx intlayer-cli init --interactive

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

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

   bash

   复制内容

   复制代码

   复制代码到剪贴板

   npm install intlayer vue-intlayer nuxt-intlayer @intlayer/vue-i18n @intlayer/sync-json-plugin

   你可以在迁移期间安全地保持 @nuxtjs/i18n 已安装状态，尽管稍后你将从 Nuxt 配置中删除它。

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

   source 将语言环境映射到其 JSON 文件路径。location 告诉 Intlayer 观察器监控哪个文件夹以查找更改。format: 'icu' 选项确保占位符被正确解析以供 vue-i18n 使用。

3. 3

   更新 Nuxt 配置

   在 nuxt.config.ts 中用 nuxt-intlayer 替换 @nuxtjs/i18n 模块。Intlayer 插件自动注入模块别名，这意味着你现有的 import { useI18n } from 'vue-i18n' 调用被透明地重定向到 @intlayer/vue-i18n。

   nuxt.config.ts

   复制内容

   复制代码

   复制代码到剪贴板

   export default defineNuxtConfig({
     // 移除 '@nuxtjs/i18n'
     modules: ["nuxt-intlayer"],
   });

   你不再需要定义 Nuxt i18n 配置对象。 Intlayer 在构建时编译所有字典，无缝处理语言环境检测、路由和字典加载。

快速迁移就这样。你的 Nuxt 应用现在在 Intlayer 上运行，同时保持所有 $t 和 useI18n() 完好无损。

完整迁移

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

1. 4

   显式导入重命名（可选）

   可选

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

   显示表格的所有内容

   显示表格的所有内容

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

   之前	之后
   import { useI18n } from 'vue-i18n'	import { useI18n } from '@intlayer/vue-i18n'

   这些是即插即用的替代品 — 不需要对调用签名、参数或返回类型进行任何更改。

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

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

迁移后可以删除的内容

兼容适配器就位后，可以移除以下样板代码：

当你准备继续深入时，Intlayer 会自动发现代码库中任何位置的所有 .content.ts 和 .content.json 文件（默认情况下，在 ./src 内的任何位置）。你可以将 my-component.content.ts 文件放在你的 MyComponent.vue 旁边，Intlayer 会在构建时自动获取它，无需任何额外配置 — 无需导入、无需注册、无需中央索引文件。这使得将翻译与页面和组件共置变得完全无摩擦。

配置 TypeScript

Intlayer 使用模块增强来为你的翻译键提供完整的 TypeScript 智能感知。确保你的 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 Nuxt — Nuxt 完整设置指南：intlayerwithnuxt.md
• Intlayer with Vue — Vue 完整设置指南：intlayerwithvite+vue.md