自动导入#

自动导入默认关闭。未配置时，请从 virtual:ai-i18n 显式导入 Runtime API：

import { t } from 'virtual:ai-i18n';

#开启自动导入

如果希望省略这些 import，请显式设置 autoImport: true：

// vite.config.ts
import { aiI18n } from '@ai-i18n/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    aiI18n({
      sourceLang: 'zh-CN', // 源码文案使用的语言
      locales: [
        // value 是语言标识，label 是界面中的展示名称。
        { value: 'zh-CN', label: '中文' },
        { value: 'en-US', label: 'English' },
      ],
      autoImport: true, // 按框架模式注入未绑定的 Runtime API
    }),
  ],
});

插件会根据最终框架模式注入对应 API：

插件只注入没有本地 binding 的值引用，直接调用、函数传递与对象简写都支持。显式 import、 局部变量或同名函数始终优先，不会被覆盖。安装其他 Vite 插件不会自动开启该能力。

Vue 与 React build 中也可以包含普通 .js / .ts 工具模块。在这些非组件模块里使用顶层 Runtime API。Vue template、render 与 computed 可以直接使用 t()；Vue 适配器会追踪语言 revision。顶层 t 与 useI18n().t 是同一个函数，Vue 的响应式刷新来自 adapter 维护的 共享 revision，并非每个组件调用 useI18n() 后单独订阅。React 组件仍使用 useI18n() 建立订阅。 getLang() 与 getLangLoadState() 返回调用时快照，自动导入不会把它们变成 Vue Ref 或 React 响应式状态。顶层状态快照 API 不会使组件自动重新渲染，React Compiler 也不能补上 缺失的订阅。

例如 Pinia action 可以直接执行语言切换；读取 getLang() 时应把结果视为一次性快照：

import { defineStore } from 'pinia';

export const useLocaleStore = defineStore('locale', {
  actions: {
    async switchLanguage(locale: string) {
      await setLang(locale);
    },
    readCurrentLanguage() {
      return getLang();
    },
  },
});

Vue setup 中需要预先声明响应式 label 或文案树时，可以使用 Vue-only tRef()。它返回只读 计算属性，不需要先调用 useI18n()：

<script setup lang="ts">
const label = tRef('保存');
const labels = tRef({
  save: '保存',
  cancel: '取消',
});
</script>

<template>{{ label }} / {{ labels.cancel }}</template>

整棵静态文案树不要求 as const 或 defineI18nMessages()。

不要在 template 中直接调用 tRef()，否则每次渲染都会创建新的 computed。

Vue 的 <script setup>、普通 <script> 与 template 都可以直接写未绑定的 t()。 生成的主声明与 Vue template 类型桥分别覆盖 TypeScript 作用域和 template，因此 Volar 与 vue-tsc 无需额外的占位 import：

<script setup lang="ts">
const { currentLang, isLangLoading, setLang } = useI18n();
</script>

<template>
  <button :disabled="isLangLoading">{{ t('保存') }}</button>
</template>

这里的顶层 t 与 useI18n().t 是同一个函数。新代码需要响应式语言状态时， useI18n() 通常只解构 Ref 和 action。

纯 Options API 不需要用 methods: { t } 建立模板桥接。脚本中的 computed / method 与 template 都可以直接调用词法作用域或模板作用域中的 t()：

<script lang="ts">
import { defineComponent } from 'vue';

export default defineComponent({
  computed: {
    ...i18nComputed(),
    buttonLabel: tComputed('保存'),
    label() {
      return t('保存');
    },
  },
});
</script>

<template>
  {{ t('保存') }} / {{ label }} / {{ buttonLabel }} / {{ currentLang }}
</template>

插件只为未绑定的值引用注入 API。模板局部变量以及组件自身的 prop、data、computed、 method、inject 或 setup 返回值会遮挡自动导入；本地同名 binding 始终优先。this.t()、 this.$t()、mixin 与 globalProperties 不属于 ai-i18n 调用。

#关闭自动导入时

autoImport: false 时仍需从 virtual:ai-i18n 显式导入。<script setup> 的顶层 import 会自然暴露给 template：

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

<template>{{ t('保存') }}</template>

普通 Options <script> 的 import 只存在于模块作用域。template 需要直接调用 t() 时， 应建立真实组件 binding：

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

export default defineComponent({
  methods: { t },
});
</script>

<template>{{ t('保存') }}</template>

这项显式导入 bridge 的静态边界见 Vue 文案写法。

顶层 t 应在实际需要文案时调用，不要在模块初始化期间保存译后字符串：

export const label = t('保存'); // 不会刷新；ESLint preset 会 warning
export const getLabel = () => t('保存'); // 每次调用读取当前语言

#TypeScript 支持

自动导入依靠插件生成的 TypeScript 声明。Vue 模式还会生成相邻的 .vue.d.ts template 类型桥。两个文件的职责、自定义 dts 路径和常见类型问题统一见 TypeScript 与生成声明。

#ESLint 配置

TypeScript 声明不会自动配置 ESLint。开启自动导入后，请按最终框架模式使用 @ai-i18n/eslint-plugin 的 configs['vanilla-auto-import']、 configs['vue-auto-import'] 或 configs['react-auto-import']。这些预设会声明对应的 只读全局，并检查静态提取语法。完整配置见 ESLint。它们还会提示初始化期译文快照；React preset 会提示 组件渲染路径中没有订阅的顶层 t。Vue / React preset 都会检查模块顶层或组件渲染中的 getLang() / getLangLoadState() 快照。如果项目希望禁止自动导入模式中残留的 virtual:ai-i18n 显式导入，可以按完整框架 API 列表额外启用可自动修复的 ai-i18n/no-redundant-auto-import；该规则默认不包含在 preset 中。