从 vue-i18n 迁移到 Intlayer

为什么要从 vue-i18n 迁移到 Intlayer？

迁移策略

从 vue-i18n 迁移到 Intlayer 有两种互补的策略：

1. 兼容适配器（推荐用于现有应用） —— 安装 @intlayer/vue-i18n（用于 Vue 组件）。此 package 暴露与 vue-i18n 完全相同的 API，但在幕后将所有翻译工作委托给 Intlayer。您保留现有的 $t、useI18n() 和 <i18n-t> 调用 —— 唯一的变化是 import 路径和初始化。

2. 完整迁移 —— 逐步将 vue-i18n API 替换为原生 Intlayer hooks（useIntlayer）并在组件旁边的 .content.ts 文件中共同定位内容。

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

目录

快速迁移

以下步骤是让现有 vue-i18n 应用在 Intlayer 上运行所需的最少步骤，组件代码零更改。

1. 1

   安装依赖

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

   bash

   复制内容

   复制代码

   复制代码到剪贴板

   npx intlayer-cli init --interactive

   --interactive flag 是可选的。如果您是 AI agent，请使用 intlayer-cli init。

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

   bash

   复制内容

   复制代码

   复制代码到剪贴板

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

   您可以保留 vue-i18n installed —— 兼容适配器使用它作为 devDependency / peerDependency 的 TypeScript 类型。

2. 2

   配置 Intlayer

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

   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,
         // 在这里添加所有现有 locale
       ],
       defaultLocale: Locales.ENGLISH,
     },
     plugins: [
       syncJSON({
         // 匹配 vue-i18n 占位符语法：{name}
         format: "icu",
         source: ({ locale }) => `./src/locales/${locale}.json`,
         location: "src/locales",
       }),
     ],
   };
   
   export default config;

   source 将 locale 映射到其 JSON 文件路径。location 告诉 Intlayer watcher 监视哪个文件夹以获取更改。format: 'icu' 选项确保正确解析 vue-i18n 的占位符。

3. 3

   将 Intlayer Plugin 添加到您的 Bundler

   用兼容 plugin 包装您现有的 bundler 配置。它组合了核心 Intlayer plugin、连接内容 watching，以及 —— 至关重要的是 —— 注入一个 module alias，使您现有的 import … from 'vue-i18n' 调用在构建时透明地重定向到 @intlayer/vue-i18n。无需更改源文件。

   对于 Vite：

   vite.config.ts

   复制内容

   复制代码

   复制代码到剪贴板

   import { defineConfig } from "vite";
   import vue from "@vitejs/plugin-vue";
   import { vueI18nVitePlugin } from "@intlayer/vue-i18n/plugin";
   
   export default defineConfig({
     plugins: [vue(), vueI18nVitePlugin()],
   });

   vueI18nVitePlugin() 包装了 vite-intlayer 的 intlayer() plugin 并添加了 vue-i18n alias。使用来自 vite-intlayer 的普通 intlayer() plugin 会编译 dictionary，但不添加 alias —— 然后您需要手动将 import 重命名为 @intlayer/vue-i18n（见步骤 4）。

   对于 Nuxt：

   如果您使用 @nuxtjs/i18n（Nuxt 集成），安装 nuxt-intlayer 并将其添加到您的 nuxt.config.ts：

   bash

   复制内容

   复制代码

   复制代码到剪贴板

   npm install nuxt-intlayer

   nuxt.config.ts

   复制内容

   复制代码

   复制代码到剪贴板

   export default defineNuxtConfig({
     modules: ["nuxt-intlayer"],
     // 您可以安全地从 modules 中移除 @nuxtjs/i18n
   });

   您不再需要 createI18n() 或手动 provider 引导。Intlayer 在构建时编译所有 dictionary，因此没有运行时加载步骤。别名 provider 为您处理初始化。

快速迁移就这样。您的应用现在在 Intlayer 上运行，同时保持每个 vue-i18n import 和 API 完整。

类型化 translation key —— 自动。Intlayer 编译 dictionary 后，当您传递 namespace 选项时，useI18n 会针对您的实际内容进行类型化。Key 会在您的 IDE 中自动完成，无效路径会在构建时导致 TypeScript 错误 —— 无需额外设置。

ts

复制内容

复制代码

复制代码到剪贴板

// 'about' 是一个已注册的 dictionary keyconst { t } = useI18n({ namespace: "about" });t("counter.label"); // ✓ 自动完成t("does.not.exist"); // ✗ TypeScript 错误

完整迁移

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

1. 4

   显式 import 重命名（可选）

   可选

   Intlayer plugin 已在 bundler 级别处理别名。如果您更喜欢在源文件中显式化依赖，可以手动重命名 import：

   显示表格的所有内容

   显示表格的所有内容

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

   之前	之后
   import { useI18n } from 'vue-i18n'	import { useI18n } from '@intlayer/vue-i18n'
   import { createI18n } from 'vue-i18n'	import { createI18n } 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 }) => `./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 文档。

迁移后可以删除的内容

兼容适配器就位后，可以删除以下 vue-i18n 样板代码：

当您准备进一步进行时，Intlayer 自动发现代码库中任何地方的所有 .content.ts 和 .content.json 文件（默认在 ./src 内的任何地方）。您可以将 my-component.content.ts 文件放在 MyComponent.vue 旁边，Intlayer 会在构建时选中它，无需额外配置 —— 无需 import、无需注册、无需集中索引文件。这使得与页面和组件共同定位翻译完全无摩擦。

配置 TypeScript

Intlayer 使用 module augmentation 为您的 translation key 提供完整的 TypeScript intellisense。确保您的 tsconfig.json 包括自动生成的类型：

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

Git 配置

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

# 忽略 Intlayer 生成的文件.intlayer

更进一步

• Visual Editor —— 在浏览器中可视化管理翻译：Intlayer Visual Editor
• CMS —— 远程外部化和管理内容：Intlayer CMS
• VS Code Extension —— 获取自动完成和实时翻译错误检测：Intlayer VS Code Extension
• CLI 参考 —— 完整的 CLI 命令列表：Intlayer CLI
• Intlayer with Vue —— Vue 完整设置指南：intlayerwithvite+vue.md
• Intlayer with Nuxt —— Nuxt 完整设置指南：intlayerwithnuxt.md