Vue 快速上手#

#开始前

ai-i18n 要求 Vite 8 或更高版本，并且当前只支持浏览器端应用。需要 SSR、按请求选择语言或避免首屏 源码回退的项目，暂不适合接入当前版本。

#创建项目

下面以 pnpm 和 Vite 的 vue-ts 模板为例：

pnpm create vite ai-i18n-vue --template vue-ts
cd ai-i18n-vue
pnpm install
pnpm add @ai-i18n/vite@alpha

项目尚未发布正式版。正式版发布前请保留 @alpha，避免安装到较旧的 latest。

已有 Vite + Vue 项目可以跳过创建步骤，直接安装 @ai-i18n/vite@alpha。请保留现有的 @vitejs/plugin-vue，无需安装额外的 ai-i18n Vue 适配包。

#配置 Vite

在 vite.config.ts 中注册 aiI18n()：

import { aiI18n } from '@ai-i18n/vite';
import vue from '@vitejs/plugin-vue';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    aiI18n({
      sourceLang: 'zh-CN',
      locales: [
        { value: 'zh-CN', label: '中文' },
        { value: 'en-US', label: 'English' },
      ],
    }),
    vue(),
  ],
});

ai-i18n 会从最终的 Vite 插件列表识别 Vue 模式。只有自定义插件环境无法识别时，才需要显式 设置 framework: 'vue'。

#编写第一个翻译组件

选择项目正在使用的 Vue API 风格，将 src/App.vue 替换为对应示例。新组件推荐使用 <script setup>；已有纯 Options API 组件可以保持原有风格。

<script setup lang="ts">
import { t, useI18n } from 'virtual:ai-i18n';

const { currentLang, langs, setLang } = useI18n();

async function changeLanguage(value: string) {
  try {
    await setLang(value);
  } catch {
    // 切换失败时保留当前语言；完整项目可显示 langLoadState 中的错误。
  }
}
</script>

<template>
  <main>
    <p>{{ t('保存') }}</p>
    <select
      :value="currentLang"
      @change="changeLanguage(($event.target as HTMLSelectElement).value)"
    >
      <option v-for="lang in langs" :key="lang.value" :value="lang.value">
        {{ lang.label }}
      </option>
    </select>
  </main>
</template>

<script lang="ts">
import { defineComponent } from 'vue';
import { i18nComputed, setLang, t } from 'virtual:ai-i18n';

export default defineComponent({
  computed: {
    ...i18nComputed(),
  },
  methods: {
    t,
    async changeLanguage(event: Event) {
      const target = event.currentTarget;
      if (!(target instanceof HTMLSelectElement)) return;
      try {
        await setLang(target.value);
      } catch {
        // 切换失败时保留当前语言。
      }
    },
  },
});
</script>

<template>
  <main>
    <p>{{ t('保存') }}</p>
    <select :value="currentLang" @change="changeLanguage">
      <option v-for="lang in langs" :key="lang.value" :value="lang.value">
        {{ lang.label }}
      </option>
    </select>
  </main>
</template>

两种写法使用同一个 Vue Runtime。顶层 t 会追踪语言 revision，因此 template 文案会随 语言切换刷新。Options API 的 defineComponent() 与 watch 参数类型问题见 TypeScript 与生成声明。

#运行与验证

pnpm dev
pnpm build

打开开发页面后切换语言。缺少目标译文时，t() 会先回退源码文案。首次接入后执行完整 Build，确认入口可达源码均已提取，并检查以下文件：

src/ai-i18n.d.ts
i18n/translations/
i18n/overrides.json
i18n/extracted/
i18n/locales/
i18n/storage.json  # 仅 SQLite

应提交声明和项目内译文；SQLite 还需提交存储标记。忽略可重新生成的 extracted/ 与 locales/。 完整规则见 生成文件与 Git。

#接入 UI 组件库

ai-i18n 负责业务文案，组件库内置文案仍由组件库自己的 locale 控制。常见组件库都可以从 currentLang 派生 locale，再传给根部的 Config Provider：

以 Element Plus 为例：

<script setup lang="ts">
import { computed } from 'vue';
import { ElConfigProvider } from 'element-plus';
import en from 'element-plus/es/locale/lang/en';
import zhCn from 'element-plus/es/locale/lang/zh-cn';
import { useI18n } from 'virtual:ai-i18n';

const { currentLang } = useI18n();
const uiLocale = computed(() => (currentLang.value === 'en-US' ? en : zhCn));
</script>

<template>
  <ElConfigProvider :locale="uiLocale">
    <RouterView />
  </ElConfigProvider>
</template>

Ant Design Vue 使用相同方式，把 locale 传给 ConfigProvider。日期组件还需同步 Day.js 等 日期库的 locale。

#下一步

• Vue 常见问题：排查模板 binding、Options 响应式状态和翻译 getter。
• 保存语言偏好：按需使用 localStorage 记住用户选择。
• 测试（Vitest）：使用 Vue 插件与专用内存 Runtime 测试组件。
• 自动导入：显式开启后可直接省略 t 等 import。
• TypeScript 与生成声明：了解 Vue 的两个声明文件并排查类型问题。
• Vue 在线演示：查看可交互的完整示例。