---
url: https://bosens-china.github.io/ai-i18n/guide/getting-started/vanilla.md
---

# Vanilla 快速上手

## 开始前

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

## 创建项目

下面以 pnpm 和 TypeScript 模板为例：

```sh
pnpm create vite ai-i18n-vanilla --template vanilla-ts
cd ai-i18n-vanilla
pnpm install
pnpm add @ai-i18n/vite@alpha
```

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

已有 Vite 项目可以跳过创建步骤，直接安装 `@ai-i18n/vite@alpha`。

## 配置 Vite

在 `vite.config.ts` 中注册 `aiI18n()`。没有检测到 Vue 或 React Vite 插件时，插件自动使用
Vanilla 模式：

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

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

## 翻译并更新 DOM

从虚拟模块导入 Runtime API。Vanilla 模式需要在语言变化后主动更新 DOM：

```ts
import { getLangs, setLang, subscribe, t } from 'virtual:ai-i18n';

function render() {
  document.querySelector('#app')!.textContent = t('保存');
}

render();
const unsubscribe = subscribe(render);

console.log(getLangs());
await setLang('en-US');

window.addEventListener('pagehide', () => unsubscribe(), { once: true });
```

## 运行与验证

```sh
pnpm dev
pnpm build
```

Dev 只提取浏览器实际请求过的模块。首次接入后应执行一次完整 Build，确认入口可达源码均已
提取。生成文件及 Git 提交规则见[生成文件与 Git](/ai-i18n/guide/basic/directory.md)。

## 下一步

- [保存语言偏好](/ai-i18n/api/vite/interfaces/ai-i18n-persist-options.md)：按需使用 localStorage 记住用户选择。
- [测试（Vitest）](/ai-i18n/guide/quality/testing.md)：使用专用内存 Runtime 测试业务模块。
- [通用文案写法](/ai-i18n/guide/basic/static-analysis/common.md)：处理动态值、文案集合和业务枚举。



---
url: https://bosens-china.github.io/ai-i18n/guide/getting-started/vue.md
---

# Vue 快速上手

## 开始前

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

## 创建项目

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

```sh
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()`：

```ts
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**

`useI18n()` 返回的语言状态是只读 Ref。脚本中读取它们需要 `.value`，template 会自动解包。
```vue title="src/App.vue"
<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>
```


**Options API**

纯 Options API 组件把 `i18nComputed()` 展开到 `computed`，获得已经解包的语言状态。
```vue title="src/App.vue"
<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>
```
当前示例使用显式导入，因此普通 `<script>` 中的 `t` 需要通过 `methods: { t }` 暴露给
template。开启 `autoImport: true` 后，应同时删除 `t` import 和这个 method bridge。


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

## 运行与验证

```sh
pnpm dev
pnpm build
```

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

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

应提交声明和项目内译文；SQLite 还需提交存储标记。忽略可重新生成的 `extracted/` 与 `locales/`。
完整规则见 [生成文件与 Git](/ai-i18n/guide/basic/directory.md)。

## 接入 UI 组件库

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

| 组件库            | Config Provider    | Locale 模块                       |
| -------------- | ------------------ | ------------------------------- |
| Element Plus   | `ElConfigProvider` | `element-plus/es/locale/lang/*` |
| Ant Design Vue | `ConfigProvider`   | `ant-design-vue/es/locale/*`    |

以 Element Plus 为例：

```vue
<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 常见问题](/ai-i18n/guide/faq/vue.md)：排查模板 binding、Options 响应式状态和翻译 getter。
- [保存语言偏好](/ai-i18n/api/vite/interfaces/ai-i18n-persist-options.md)：按需使用 localStorage 记住用户选择。
- [测试（Vitest）](/ai-i18n/guide/quality/testing.md)：使用 Vue 插件与专用内存 Runtime 测试组件。
- [自动导入](/ai-i18n/guide/basic/auto-import.md)：显式开启后可直接省略 `t` 等 import。
- [TypeScript 与生成声明](/ai-i18n/guide/quality/typescript.md)：了解 Vue 的两个声明文件并排查类型问题。
- [Vue 在线演示](/ai-i18n/demo/vue.md)：查看可交互的完整示例。



---
url: https://bosens-china.github.io/ai-i18n/guide/getting-started/react.md
---

# React 快速上手

## 开始前

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

## 创建项目

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

```sh
pnpm create vite ai-i18n-react --template react-ts
cd ai-i18n-react
pnpm install
pnpm add @ai-i18n/vite@alpha
```

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

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

## 配置 Vite

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

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

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

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

## 编写第一个翻译组件

将 `src/App.tsx` 替换为：

```tsx
import { useI18n } from 'virtual:ai-i18n';

export default function App() {
  const { currentLang, langs, setLang, t } = useI18n();

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

  return (
    <main>
      <p>{t('保存')}</p>
      <select
        value={currentLang}
        onChange={(event) => void changeLanguage(event.target.value)}
      >
        {langs.map((lang) => (
          <option key={lang.value} value={lang.value}>
            {lang.label}
          </option>
        ))}
      </select>
    </main>
  );
}
```

组件需要展示随语言变化的文案时，应使用 `useI18n()` 返回的 `t`。不要在渲染路径中只调用
Runtime 顶层 `t`，否则组件不会建立订阅。

## 运行与验证

```sh
pnpm dev
pnpm build
```

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

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

应提交声明和项目内译文；SQLite 还需提交存储标记。忽略可重新生成的 `extracted/` 与 `locales/`。
完整规则见 [生成文件与 Git](/ai-i18n/guide/basic/directory.md)。

## 接入 UI 组件库

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

| 组件库        | Provider         | Locale 模块              |
| ---------- | ---------------- | ---------------------- |
| Ant Design | `ConfigProvider` | `antd/locale/*`        |
| MUI        | `ThemeProvider`  | `@mui/material/locale` |

以 Ant Design 为例：

```tsx
import { ConfigProvider } from 'antd';
import enUS from 'antd/locale/en_US';
import zhCN from 'antd/locale/zh_CN';
import type { PropsWithChildren } from 'react';
import { useI18n } from 'virtual:ai-i18n';

export function AppLocale({ children }: PropsWithChildren) {
  const { currentLang } = useI18n();
  const locale = currentLang === 'en-US' ? enUS : zhCN;

  return <ConfigProvider locale={locale}>{children}</ConfigProvider>;
}
```

MUI 使用 `createTheme({}, locale)` 创建本地化主题，再交给 `ThemeProvider`。MUI X Date
Pickers 还需同步日期适配器的 locale。

## 下一步

- [React 常见问题](/ai-i18n/guide/faq/react.md)：排查 JSX 提取、组件订阅与 React Compiler。
- [保存语言偏好](/ai-i18n/api/vite/interfaces/ai-i18n-persist-options.md)：按需使用 localStorage 记住用户选择。
- [测试（Vitest）](/ai-i18n/guide/quality/testing.md)：使用 React 插件与专用内存 Runtime 测试组件。
- [自动导入](/ai-i18n/guide/basic/auto-import.md)：显式开启后省略 `useI18n` import。
- [React 在线演示](/ai-i18n/demo/react.md)：查看可交互的完整示例。



---
url: https://bosens-china.github.io/ai-i18n/guide/basic/static-analysis/common.md
---

# 通用文案写法

ai-i18n 只处理明确传给翻译 API 的文案，不会猜测哪些普通文本需要翻译。因此，请把需要翻译的
内容写入 `t()`。

本页介绍三个框架共用的写法。框架差异见 [Vue 文案写法](/ai-i18n/guide/basic/static-analysis/vue.md) 和
[React 文案写法](/ai-i18n/guide/basic/static-analysis/react.md)。

## 支持的源码

| 模式      | 参与提取的源码                                        |
| ------- | ---------------------------------------------- |
| Vanilla | `.js`、`.mjs`、`.ts`、`.mts`                      |
| Vue     | `.js`、`.mjs`、`.ts`、`.mts`、`.jsx`、`.tsx`、`.vue` |
| React   | `.js`、`.mjs`、`.ts`、`.mts`、`.jsx`、`.tsx`        |

表中的 JavaScript 与 TypeScript 源码必须作为浏览器端 ESM 模块使用。ai-i18n 不处理
`.cjs`、`.cts`，也不识别通过 `require()` 获得的翻译 API。Vite 对配置文件或依赖中
CommonJS 的兼容，不代表这些文件会参与 ai-i18n 提取。

`index.html` 默认不参与提取。设置 `html: true` 后，插件会分析完整的 `t()` 文本节点，
以及 `alt`、`aria-label`、`placeholder`、`title` 属性：

```ts
aiI18n({
  // 省略 sourceLang 与 locales 等基础配置。
  html: true,
});
```

普通 HTML 文本、混合文本（例如 `前缀 t('保存')`）、非白名单属性和内联脚本不会由
HTML 提取器处理。

## 识别 `t()`

可以从 `virtual:ai-i18n` 导入 `t`，也可以在导入时改名：

```ts
import { t as translate } from 'virtual:ai-i18n';

translate('保存');
```

Vue 或 React 构建中的普通 ESM 工具模块也可以显式导入顶层 `t`：

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

export const getRetryMessage = () => t('请重试');
```

开启 [自动导入](/ai-i18n/guide/basic/auto-import.md) 后，可以省略导入。局部变量、函数参数和显式导入的同名
标识符仍按你的代码处理，不会被覆盖。

## 支持的参数

日常文案优先使用字符串、静态 `const` 或条件表达式：

```ts
t('保存');

const label = '取消';
t(label);

t(canSubmit ? '提交' : '返回');
```

动态值使用 tagged template。表达式会变成可重排的编号占位符，不会发送给翻译模型：

```ts
t`你好 ${user.name}，你有 ${unreadCount} 条消息`;
```

需要返回 HTML 字符串时，不要把结构性标签写进待翻译文案。把由代码维护的 HTML 片段作为
插值传入，让译文只负责自然语言、标点、单位和占位符顺序：

```ts
const valueHtml = `<span style="font-weight:bold">${voltage}</span>`;

t`电压：${valueHtml} V`;
```

这条文案会提取为 `电压：{{0}} V`。翻译者可以调整语序和单位，但不需要维护 `<span>` 标签。
传入的动态内容仍应来自可信数据或完成必要的转义；模板插值不会自动净化 HTML。
启用 [`ai-i18n/no-embedded-markup`](/ai-i18n/guide/quality/eslint-rules.md#no-embedded-markup) 后，
ESLint 会对最终可提取 source 中的静态 HTML 或 SVG 发出 warning。

需要一次得到整组译文时，可以直接传入静态纯文案树：

```ts
const messages = {
  actions: { save: '保存', cancel: '取消' },
  states: ['等待中', '处理中', '已完成'],
};

const labels = t(messages);
```

所有字符串叶子都会翻译。本地或导入的静态 `const` 都可使用，不需要 `as const`。

需要按属性或索引挑选单条文案时，使用无需 import 的编译宏：

```ts
const messages = defineI18nMessages({
  actions: { save: '保存', cancel: '取消' },
  states: ['等待中', '处理中', '已完成'],
});

t(messages.actions.save);
t(messages.states[index]);
```

`defineI18nMessages()` 同样适用于普通 `.js` / `.ts` 文件。它不需要 import；TypeScript
类型来自 Vite 生成的主声明。编辑器找不到该名字时，按
[TypeScript 与生成声明](/ai-i18n/guide/quality/typescript.md)排查。

### 动态业务数据只翻译展示标签

数据库、接口参数和业务判断应保存稳定 code，不要保存当前语言的译文。为有限枚举建立静态
文案映射，在展示时按 code 选择并翻译：

```ts
type SportType = 'running' | 'cycling' | 'swimming';

const sportLabels = defineI18nMessages<Record<SportType, string>>({
  running: '跑步',
  cycling: '骑行',
  swimming: '游泳',
});

export function getSportLabel(sportType: SportType) {
  return t(sportLabels[sportType]);
}
```

例如记录中始终保存 `running`，界面才根据当前语言显示“跑步”或“Running”。这样切换语言不会
改变持久数据，排序、筛选和接口契约也不依赖展示文案。运行时可能出现未知 code 时，先由业务代码
决定回退或报错，不要把不受约束的动态字符串直接传给 `t()`。

翻译注释同样需要静态求值：

```ts
t('保存', { comment: '工具栏按钮' });

const options = { comment: '结算按钮' };
t('提交', options);
```

`comment` 只用于说明翻译语境。相同原文在不同语境下可以得到不同译文。

## 推荐写法与限制

| 写法                                   | Vite 提取   | ESLint   |
| ------------------------------------ | --------- | -------- |
| `t('保存')`                            | 提取        | 允许       |
| `const label = '保存'; t(label)`       | 提取        | 允许       |
| `t(ok ? '保存' : '取消')`                | 提取两个候选    | 允许       |
| `` t`你好 ${name}` ``                  | 提取编号模板    | 允许       |
| `t({ save: '保存', states: ['等待中'] })` | 提取所有字符串叶子 | 允许       |
| `t(messages.states[index])`，集合已用宏标记  | 提取有限候选    | 允许       |
| `t('保' + '存')`                       | 不推荐       | 报错       |
| `t(ok && '保存')`                      | 不推荐       | 报错       |
| `let label = '保存'; t(label)`         | 不推荐       | 报错       |
| 普通对象或数组成员传给 `t()`                    | 使用宏       | 报错并建议使用宏 |

建议启用 [ESLint](/ai-i18n/guide/quality/eslint.md)，在本地尽早发现不推荐的写法。

## 提取成功不等于会刷新

文案被识别不代表界面会自动刷新。语言切换后的更新还取决于 `t()` 的执行时机：

| 写法                                      | 提取 | 语言切换行为          |
| --------------------------------------- | -- | --------------- |
| `export const label = t('保存')`          | 是  | 初始化时保存快照，不会自动更新 |
| `export const getLabel = () => t('保存')` | 是  | 每次调用读取当前语言      |

组件还需要建立框架订阅。具体规则见 [Vue 文案写法](/ai-i18n/guide/basic/static-analysis/vue.md) 和
[React 文案写法](/ai-i18n/guide/basic/static-analysis/react.md)。

## 不支持的写法

- 不提取普通字符串、普通 JSX 文本、普通 Vue 模板文本或普通 HTML 文本。
- 函数调用、`await`、`JSON.parse()` 和其他运行时结果不能作为 `t()` 参数。
- 普通对象或数组成员需要先用 `defineI18nMessages()` 标记，才能按属性或索引选择文案。
- 文案树只适合普通对象、数组和基础值；不要混入路由、业务 key、函数或运行时数据。
- 普通 JSX、Vue 模板和 HTML 文本不会自动翻译，必须显式调用翻译 API。
- 开发服务器只处理已访问模块；提交或补译前请运行完整 Build。
- 当前运行时只支持浏览器端，不支持 SSR。

完整签名与边界见 [`t()`](/ai-i18n/api/runtime/functions/t.md)。



---
url: https://bosens-china.github.io/ai-i18n/guide/basic/static-analysis/vue.md
---

# Vue 文案写法

本页只介绍 Vue 特有写法。参数、文案树和宏的通用规则见[通用文案写法](/ai-i18n/guide/basic/static-analysis/common.md)。

## 支持的源码

Vue 模式分析 `.js`、`.mjs`、`.ts`、`.mts`、`.jsx`、`.tsx` 与 `.vue` 源码。JavaScript
与 TypeScript 模块必须使用 ESM，不支持 `.cjs`、`.cts` 或 CommonJS 调用方式。JSX/TSX
项目需要使用 `@vitejs/plugin-vue-jsx`。

Vue SFC 会分析 `<script>`、`<script setup>` 和 template 表达式。模板中的 `v-for`
局部变量、slot 局部变量与组件自身同名 binding 会保留各自作用域，不会误判为翻译 API。

## 直接使用 `t`

自动导入默认关闭。此时新组件推荐在 `<script setup lang="ts">` 顶层显式导入 `t`。顶层
import 会自然成为 template binding，Volar 与 `vue-tsc` 也能直接识别：

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

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

普通 Options API 也调用同一个顶层 `t`：

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

export default defineComponent({
  computed: {
    label() {
      return t('保存');
    },
  },
  methods: {
    // 让 Vue template 与 Volar 都获得真实的组件 binding。
    t,
    notify() {
      return t('保存成功');
    },
  },
});
</script>

<template>
  <button :title="label" @click="notify">{{ t('保存') }}</button>
</template>
```

普通 Options 的 import 不会自动成为组件实例属性，因此 template 要直接写 `t()` 时，需要
像上例一样把它暴露为 `methods: { t }`。这是一个真实的 Vue method，不使用
`globalProperties`。脚本内仍直接调用词法作用域中的 `t()`，不要改写成 `this.t()`。

`useI18n().t` 与顶层导出的 `t` 是同一个函数。它们都读取 Vue adapter 维护的共享
revision；template、render 或 computed 执行 `t()` 时，Vue 会收集这项依赖。响应式刷新
不是由每个组件调用 `useI18n()` 后单独订阅得到的。

新代码需要语言状态或 action 时，让 `useI18n()` 只提供这些值即可：

```ts
import { t, useI18n } from 'virtual:ai-i18n';

const { currentLang, isLangLoading, setLang } = useI18n();
```

`useI18n()` 仍返回 `t`，既有解构写法与顶层 import 完全等价，不属于废弃能力。

开启 `autoImport: true` 后，可以删除 `t` 的 import。`<script setup>`、普通 `<script>`、
纯 Options 与只有 template 的 SFC 都可以直接使用裸 `t()`：

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

插件生成的 `ai-i18n.d.ts` 同时声明 script 全局 API 和 Vue template 中的 `t`。因此 Volar
与 `vue-tsc` 能直接识别上面的写法，无需补充 import 或 `methods: { t }`。

template 提取和自动注入目前只覆盖默认 HTML template 与 `lang="html"`。`lang="pug"` 等
预处理模板不会提取或注入裸 `t()`；请在 `<script>` 或 computed 中完成翻译，再让模板读取
结果。

自动导入只处理未绑定的 `t`。模板局部变量以及组件自身的 prop、data、computed、method、
inject 或 setup 返回值具有更高优先级。`this.t`、`this.$t`、mixin 与
`globalProperties` 不属于静态提取写法。

## 显式导入下的 Options bridge

关闭自动导入后，普通 Options `<script>` 的显式 import 不会成为 template binding。
`methods: { t }` bridge 只在分析器能静态证明直接根 Options 时参与提取：Vue SFC 必须直接
导出对象字面量，或把对象字面量直接传给已识别的 `defineComponent()`。

根对象顶层出现任意 spread、`extends` 或 `mixins` 时，分析器会保守禁用这个 template
bridge。即使 Vue 运行时能够合并 method，Volar 也能提供类型，也不能据此判断 `t` 一定来自
ai-i18n。此时 template 中的 `t()` 不会提取；请把 `methods: { t }` 放回直接根 Options，
或者在 computed 中词法调用导入的 `t()`，再让 template 使用 computed 结果。

`useI18n()` 用于读取 `currentLang`、`langs` 和语言包加载状态，也兼容从返回值直接取得
`t`。完整返回值见 [Vue `useI18n()` API](/ai-i18n/api/runtime/vue/use-i18n.md)。

## 响应式翻译 getter

Vue 模式还识别从 `virtual:ai-i18n` 导入的 `tRef`。`tRef` 与 `t` 使用相同的静态参数规则：

```ts
import { tRef } from 'virtual:ai-i18n';

const saveLabel = tRef('保存');
const labels = tRef({ save: '保存', cancel: '取消' });

const messages = defineI18nMessages({ save: '保存' });
const selectedLabel = tRef(messages.save);
```

普通文本、整棵静态文案树，以及宏标记后的文案树成员都可以提取。完整签名和生命周期约束见
[`tRef()` API](/ai-i18n/api/runtime/vue/t-ref.md)。

纯 Options API 使用 `tComputed()`：

```ts
import { defineComponent } from 'vue';
import { i18nComputed, tComputed } from 'virtual:ai-i18n';

export default defineComponent({
  computed: {
    ...i18nComputed(),
    saveLabel: tComputed('保存'),
    labels: tComputed({ save: '保存', cancel: '取消' }),
  },
});
```

`tComputed()` 返回 Options computed getter，支持与 `tRef()` 相同的静态参数和文案树。
完整签名见 [`tComputed()` API](/ai-i18n/api/runtime/vue/t-computed.md)。

## 提取与响应式刷新

| 写法                                            | 提取 | 语言切换行为                        |
| --------------------------------------------- | -- | ----------------------------- |
| `<script setup>` 中 `const label = t('保存')`    | 是  | setup 快照，不会自动更新               |
| `setup()` 中 `const label = t('保存')`           | 是  | setup 快照，不会自动更新               |
| Options `data()` 中保存 `t('保存')`                | 是  | data 快照，不会自动更新                |
| setup 中 `const label = tRef('保存')`            | 是  | 返回 Ref，语言切换时自动更新              |
| setup 中 `const labels = tRef(messages)`       | 是  | 整棵文案树随语言切换更新                  |
| Options `label: tComputed('保存')`              | 是  | 组件 computed 随语言切换更新           |
| Options `labels: tComputed(messages)`         | 是  | 同形文案树随语言切换更新                  |
| template、render 或 computed 中直接调用 `t`          | 是  | 追踪 Vue revision 并刷新           |
| 显式 import 后以 `methods: { t }` 暴露 `t`          | 是  | 关闭自动导入时建立真实 template binding  |
| 模板或 render 使用 `useI18n()` 返回的 `t`             | 是  | 与顶层 `t` 相同，追踪 revision 并刷新    |
| 普通 `setup()` 返回 `useI18n()` 的 `t` 或对象         | 是  | 与顶层 `t` 相同，追踪 revision 并刷新    |
| Options computed / method 中直接调用 `t`           | 是  | 每次执行时读取当前语言                   |
| `this.t`、`this.$t`、mixin 或 `globalProperties` | 否  | 不属于 ai-i18n binding           |
| 模板或 render 中直接调用 `tRef()`                     | 是  | 每次渲染创建 computed，不支持该用法        |
| data、template 或 render 中调用 `tComputed()`      | 是  | 返回 getter，不支持该用法              |
| setup、data 或 template 中调用 `i18nComputed()`    | 否  | 配置工厂位置错误，不支持该用法               |
| 仅有 template 的裸 `t`，且开启自动导入                    | 是  | Runtime、Volar 与 `vue-tsc` 均支持 |

`ai-i18n/no-eager-translation` 检查初始化快照。
`ai-i18n/no-unsubscribed-t` 仍会检查 `tRef()` 与 `tComputed()` 的错误使用位置；
`ai-i18n/no-unsubscribed-runtime-state` 检查 setup / Options data 状态快照与
`i18nComputed()` 的错误位置。

事件回调和普通延迟函数可以继续使用顶层 `t`，因为它们会在调用时读取当前语言。完整规则见
[ESLint](/ai-i18n/guide/quality/eslint.md)。



---
url: https://bosens-china.github.io/ai-i18n/guide/basic/static-analysis/react.md
---

# React 文案写法

本页只介绍 React 特有写法。参数、文案树和宏的通用规则见[通用文案写法](/ai-i18n/guide/basic/static-analysis/common.md)。

## 支持的源码

React 模式分析 `.js`、`.mjs`、`.ts`、`.mts`、`.jsx` 与 `.tsx` ESM 源码。不支持
`.cjs`、`.cts` 或 CommonJS 调用方式。普通 JSX 文本不会自动提取，文案必须传给翻译 API。

## `useI18n()` 返回的 `t`

分析器识别直接从 `useI18n()` 返回值获得的 `t`，包括解构、改名和对象成员调用：

```tsx
const { t: translate } = useI18n();
const i18n = useI18n();

translate('保存');
i18n.t('取消');
i18n['t']('返回');
```

解构或改名只改变本地变量名。`t` 仍然来自 Hook，因此不会切断语言切换时的组件刷新。
它与顶层 `t()` 使用相同的静态参数规则：

```tsx
const { t } = useI18n();

const title = t('订单详情');
const labels = t({ save: '保存', cancel: '取消' });

const messages = defineI18nMessages({ save: '保存' });
const saveLabel = t(messages.save);
```

从 Hook 结果二次解构，或直接调用 `useI18n().t()`，不在推荐范围内：

```tsx
const i18n = useI18n();
const { t } = i18n; // 不支持二次解构

useI18n().t('保存'); // 不支持链式调用
```

完整返回值见 [React `useI18n()` API](/ai-i18n/api/runtime/react/use-i18n.md)。

## 提取与组件刷新

| 写法                         | 提取 | 语言切换行为           |
| -------------------------- | -- | ---------------- |
| 组件渲染使用顶层 `t`               | 是  | 不建立订阅，不会主动重新渲染   |
| 组件渲染使用 `useI18n()` 返回的 `t` | 是  | 建立 React 订阅并重新渲染 |
| 事件回调或普通延迟函数使用顶层 `t`        | 是  | 调用时读取当前语言        |

`useI18n()` 会订阅语言变化，因此无需额外处理 React Compiler 或缓存。无论是否启用 React Compiler，
组件渲染都应使用 Hook 返回的 `t`。

`ai-i18n/no-unsubscribed-t` 会检查 JSX / TSX 渲染路径中未订阅的顶层 `t`。完整规则见
[ESLint](/ai-i18n/guide/quality/eslint.md)。



---
url: https://bosens-china.github.io/ai-i18n/guide/basic/auto-import.md
---

# 自动导入

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

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

## 开启自动导入

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

```ts
// 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：

| 模式      | 自动导入的 API                                                         |
| ------- | ----------------------------------------------------------------- |
| Vanilla | `t`、`setLang`、`getLang`、`getLangs`、`getLangLoadState`、`subscribe` |
| Vue     | 全部 Runtime API，以及 `useI18n`、`tRef`、`i18nComputed`、`tComputed`     |
| React   | 全部 Runtime API，以及 `useI18n`                                       |

插件只注入没有本地 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 也不能补上
缺失的订阅。

| 使用位置                         | 推荐 API                         |
| ---------------------------- | ------------------------------ |
| Vue template、render、computed | `t()`                          |
| React 组件渲染                   | `useI18n()`                    |
| Vue setup 中预声明响应式文案          | `tRef()`                       |
| Vue 纯 Options 响应式状态          | `i18nComputed()`               |
| Vue 纯 Options 预声明响应式文案       | `tComputed()`                  |
| 普通 TS/JS、store action、路由守卫   | 顶层 Runtime API                 |
| 非组件模块长期监听语言变化                | `subscribe()`，并在销毁时调用返回的取消订阅函数 |

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

```ts
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()`：

```vue
<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：

```vue
<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()`：

```vue
<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：

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

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

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

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

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

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

这项显式导入 bridge 的静态边界见
[Vue 文案写法](/ai-i18n/guide/basic/static-analysis/vue.md#显式导入下的-options-bridge)。

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

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

## TypeScript 支持

自动导入依靠插件生成的 TypeScript 声明。Vue 模式还会生成相邻的 `.vue.d.ts` template
类型桥。两个文件的职责、自定义 `dts` 路径和常见类型问题统一见
[TypeScript 与生成声明](/ai-i18n/guide/quality/typescript.md)。

## ESLint 配置

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



---
url: https://bosens-china.github.io/ai-i18n/guide/basic/locale-loading.md
---

# 语言分包与按需加载

默认情况下，ai-i18n 会把所有目标语言注册到同一个 Runtime。配置 `loading` 后，每个目标
locale 会生成独立的 Vite chunk；未提前加载的语言会在首次 `setLang()` 时按需加载。

## 配置分包策略

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

aiI18n({
  sourceLang: 'zh-CN', // source locale 同步可用，不生成独立语言 chunk
  // value 是语言标识，label 是界面中的展示名称。
  locales: [
    { value: 'zh-CN', label: '中文' },
    { value: 'en-US', label: 'English' },
    { value: 'ja-JP', label: '日本語' },
    { value: 'fr-FR', label: 'Français' },
  ],
  loading: {
    // 启用按 locale 分包并声明资源加载提示
    preload: ['en-US'], // 通过 modulepreload 尽早准备
    prefetch: ['ja-JP'], // 通过 prefetch 低优先级缓存
  },
});
```

| 语言      | 加载方式                                                          |
| ------- | ------------------------------------------------------------- |
| `zh-CN` | source locale，不生成语言 chunk                                     |
| `en-US` | 通过 `modulepreload` 尽早准备；非 source 的 `defaultLang` 也会自动 preload |
| `ja-JP` | 通过 `prefetch` 提示浏览器低优先级缓存                                     |
| `fr-FR` | 首次调用 `setLang('fr-FR')` 时加载                                   |

`modulepreload` 与 `prefetch` 都是浏览器调度提示，不保证资源在某个时刻已经完成下载。

如果 `defaultLang` 保持 source，并希望所有目标语言都在切换时再加载，只需传入空对象：

```ts
aiI18n({
  sourceLang: 'zh-CN', // 默认语言保持 source
  locales, // 复用上方完整语言列表
  loading: {}, // 启用分包，其他目标语言首次 setLang() 时再加载
});
```

省略 `loading` 并不等于 `loading: {}`。前者保留默认的全语言注册模式，后者会启用分包，
并让未指定的目标语言完全按需加载。

## 显示切换中的加载状态

`setLang()` 返回 Promise。目标语言 chunk 尚未加载时，它会等待资源完成；成功后才切换语言
并通知订阅者更新。Runtime 同时维护共享状态。Vue adapter 统一维护响应式 revision；
Composition 组件通过 `useI18n()` 读取共享 Ref，纯 Options 组件通过 `i18nComputed()`
读取已解包状态。React 组件通过 `useI18n()` 订阅，Vanilla JS 通过 `subscribe()` 订阅。


**Vue**

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

const { isLangLoading, langLoadState, setLang } = useI18n();

async function switchToFrench() {
  try {
    await setLang('fr-FR');
  } catch {
    // 仅在这里添加业务级恢复动作；通用错误展示直接读取 langLoadState.status。
  }
}
</script>

<template>
  <button :disabled="isLangLoading" @click="switchToFrench">
    {{ isLangLoading ? t('正在加载语言包…') : t('切换到法语') }}
  </button>
  <p v-if="langLoadState.status === 'error'">
    {{ t('语言包加载失败，请重试') }}
  </p>
  <small v-if="langLoadState.status === 'loading'">
    {{ t('目标语言：') }} {{ langLoadState.targetLang }}
  </small>
</template>
```


**Vue Options**

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

export default defineComponent({
  computed: {
    ...i18nComputed(),
  },
  methods: {
    t,
    async switchToFrench() {
      try {
        await setLang('fr-FR');
      } catch {
        // 通用错误展示直接读取响应式 langLoadState。
      }
    },
  },
});
</script>

<template>
  <button :disabled="isLangLoading" @click="switchToFrench">
    {{ isLangLoading ? t('正在加载语言包…') : t('切换到法语') }}
  </button>
  <p v-if="langLoadState.status === 'error'">
    {{ t('语言包加载失败，请重试') }}
  </p>
  <small v-if="langLoadState.status === 'loading'">
    {{ t('目标语言：') }} {{ langLoadState.targetLang }}
  </small>
</template>
```


**React**

```tsx
import { useI18n } from 'virtual:ai-i18n';

export function LanguageButton() {
  const { isLangLoading, langLoadState, setLang, t } = useI18n();

  async function switchToFrench() {
    try {
      await setLang('fr-FR');
    } catch {
      // 仅在这里添加业务级恢复动作；通用错误展示直接读取 langLoadState.status。
    }
  }

  return (
    <>
      <button
        disabled={isLangLoading}
        onClick={() => void switchToFrench()}
      >
        {isLangLoading ? t('正在加载语言包…') : t('切换到法语')}
      </button>
      {langLoadState.status === 'error' ? (
        <p>{t('语言包加载失败，请重试')}</p>
      ) : null}
      {langLoadState.status === 'loading' ? (
        <small>
          {t('目标语言：')} {langLoadState.targetLang}
        </small>
      ) : null}
    </>
  );
}
```


**Vanilla JS**

```js
import { getLangLoadState, setLang, subscribe, t } from 'virtual:ai-i18n';

const button = document.querySelector('#switch-language');
const status = document.querySelector('#language-status');

function render() {
  const state = getLangLoadState();

  button.disabled = state.status === 'loading';
  button.textContent =
    state.status === 'loading' ? t('正在加载语言包…') : t('切换到法语');
  status.textContent =
    state.status === 'error' ? t('语言包加载失败，请重试') : '';
}

button.addEventListener('click', () => {
  // 共享状态不会消费 rejected Promise，调用方仍需显式 catch。
  void setLang('fr-FR').catch(() => {});
});

render();
const unsubscribe = subscribe(render);

// 页面或视图销毁时调用 unsubscribe()。
```


加载失败时，Runtime 会保留当前语言并让 Promise reject。应用可以像上例一样捕获错误，
执行日志、重试计数等业务动作；只需要通用 UI 时可以直接使用内置状态。

普通 JavaScript / TypeScript 模块如果只需要当前值，可以读取一次快照：

```ts
import { getLangLoadState } from 'virtual:ai-i18n';

const state = getLangLoadState();
```

需要持续响应变化时，应像 Vanilla 示例一样配合 `subscribe()` 重新读取。状态的完整类型与
并发语义见 [`getLangLoadState()`](/ai-i18n/api/runtime/functions/get-lang-load-state.md)。

## 配置规则

- `preload` 与 `prefetch` 只能填写 `locales` 中的目标 locale，不能填写 `sourceLang`。
- 同一 locale 不能同时出现在两个列表中；同一列表内的重复值会自动去重。
- 非 source 的 `defaultLang` 会自动按 preload 处理。不要再把它填入 `prefetch`，否则配置会在启动时
  报错。资源就绪前先渲染 source fallback，加载完成后再通知订阅者更新。
- 相同 locale 的并发调用会复用同一次底层语言包加载请求，不保证各次 `setLang()` 返回的
  Promise 引用相等。不同 locale 的并发切换以最后一次调用为准。
- 缺失或值为 `null` 的译文始终回退到 source 文案。

完整字段类型与边界见
[`AiI18nLocaleLoadingOptions`](/ai-i18n/api/vite/interfaces/ai-i18n-locale-loading-options.md)。



---
url: https://bosens-china.github.io/ai-i18n/guide/basic/directory.md
---

# 生成文件与 Git

ai-i18n 默认在 Vite root 下创建 `i18n/` 目录，用来保存译文和本地构建产物：

```text
i18n/
├── translations/          # 默认 JSON 存储
│   ├── manifest.json
│   └── 00.json ... ff.json
├── overrides.json
├── extracted/
├── locales/
└── storage.json           # 仅 SQLite 存储
```

你通常只需要关注两类文件：

- `translations/`：默认的分片 JSON Translation Memory，保存自动翻译或 Agent 补齐的译文。
- `storage.json`：仅在选择 SQLite 时生成。缺少该文件表示使用默认 JSON；文件不包含本机数据库路径。
- `overrides.json`：人工确认过的最终译文。它优先于自动翻译结果。

`extracted/` 和 `locales/` 都是构建产物。插件会根据源码和上述译文重新生成它们，不要直接编辑。

## Git 提交规则

将以下文件与源码一起提交：

- `src/ai-i18n.d.ts`，或通过 `dts` 配置的声明文件；
- Vue 自动导入模式生成的相邻 `.vue.d.ts` 声明文件；
- `i18n/translations/**/*.json`（使用默认 JSON 存储时）；
- `i18n/storage.json`（使用 SQLite 存储时）；
- `i18n/overrides.json`。

将以下目录加入 `.gitignore`：

```text
i18n/extracted/
i18n/locales/
logs/
*.log
```

`logs/` 与 `*.log` 是 OpenAI Provider 的本地审查日志，可能包含完整提示词、业务文案和模型输出，
不得提交。使用自定义日志目录时也要忽略该目录。详情见
[LLM 日志与排障](/ai-i18n/guide/advanced/llm-logs.md)。

默认的分片 JSON 适合团队协作。它可以随源码提交，也便于在 PR 中审查译文变化。团队成员与 CI 拉取
同一份仓库后，可以直接复用已经提交的自动译文和人工译文。

:::important
译文文件与引用它们的源码应在同一个 PR 中提交。这样其他开发者和 CI 才能得到一致的翻译结果。
:::

选择 `translationMemory.storage: 'sqlite'` 时，全局数据库位于用户目录，不提交 Git；项目仍提交
`storage.json` 与 `overrides.json`。SQLite 是本机缓存，新机器和 CI 需要 Provider 重新生成自动
译文。因此，需要跨机器共享自动译文的团队应使用默认的分片 JSON。两种存储的选择见
[Translation Memory](/ai-i18n/guide/advanced/translation-memory.md)。

声明文件的作用和自定义路径见
[TypeScript 与生成声明](/ai-i18n/guide/quality/typescript.md)。

## 什么时候运行完整 Build

开发服务器只处理浏览器实际访问过的模块。以下情况请运行一次完整 `vite build`：

1. 首次接入 ai-i18n；
2. 准备补译、审校或提交译文；
3. 切换分支后，或修改了源码、Vite 配置和提取相关配置；
4. `i18n/extracted/` 缺失、为空，或不确定它是否仍与当前源码一致。

完整 Build 会处理从应用入口可达的模块。未被应用引用的文件不会进入翻译结果。

## Monorepo 中的目录归属

一个 Vite build 必须独占一个 i18n 目录。例如：

```text
apps/
├── web/
│   └── i18n/
└── admin/
    └── i18n/
packages/
└── ui/
    └── src/
```

`web` 引用 `packages/ui` 的本地 ESM 源码时，完整 Build 会把 UI 文案纳入
`apps/web/i18n`。共享源码包不需要重复注册 ai-i18n，也不需要单独创建 i18n 目录，除非它
自己拥有独立的 Vite build。

不要让 Web、Admin 或包构建共用一个目录。完整 Build 会按当前应用的模块图重建
`extracted/` 和 `locales/`，不同构建会相互覆盖。补译或审校时也应分别选择每个应用。

## 缺译时会发生什么

目标语言缺少译文时，页面会显示源码文案。你可以配置 [AI 翻译](/ai-i18n/guide/advanced/ai-translation.md)，也可以按
[补译与审校](/ai-i18n/guide/basic/translations.md) 手动处理。

同一句原文在不同语境下需要不同译法时，为 `t()` 提供 `comment`：

```ts
t('提交', { comment: '创建 Git 提交' });
t('提交', { comment: '表单按钮' });
```

## 处理合并冲突

合并冲突时保留 `translations/` 与 `overrides.json` 的有效内容，不要手工调整消息所属分片。同一人工
译文出现不同版本时，由负责人确认最终措辞。解决冲突后运行一次 Build，再检查页面效果。

如果同时使用 Agent 或 Provider 写入译文，避免在编辑器中并行手改同一份译文文件。先完成一方操作，再进行
另一方操作。



---
url: https://bosens-china.github.io/ai-i18n/guide/basic/translations.md
---

# 补译与审校

ai-i18n 不会用空字符串代替缺失译文。缺译时页面会回退显示源码文案，因此可以先完成开发，再逐步处理翻译。

## 推荐流程

1. 运行一次完整 `vite build`，让当前应用的可达文案进入翻译结果。
2. 选择一种补译方式：配置 [AI 翻译](/ai-i18n/guide/advanced/ai-translation.md)，或使用
   [Agent + MCP](/ai-i18n/guide/advanced/ai-tools.md)。
3. 检查关键页面和产品术语。
4. 对不满意或需要固定的译文进行人工审校。
5. 再运行一次 Build，并按当前存储模式提交源码、Translation Memory 标记与 `overrides.json`。

## 自动翻译与人工译文

自动翻译默认写入 `i18n/translations/` 分片。人工确认的译文写入 `i18n/overrides.json`，并且始终优先
显示。也可以将自动译文放进用户级全局 SQLite，详见
[Translation Memory](/ai-i18n/guide/advanced/translation-memory.md)。

适合人工审校的情况包括：

- 品牌名、产品术语和法律文案；
- 同一原文在不同页面代表不同含义；
- 需要符合团队既有的语言风格。

同一句原文有不同含义时，请为调用添加静态 `comment`，再按该语境分别审校：

```ts
t('保存', { comment: '保存文件按钮' });
t('保存', { comment: '保存状态' });
```

## 直接编辑译文文件

Provider 或 Agent + MCP 会自动维护文件结构，适合批量补译和按语境审校。需要手工调整少量译文时，
也可以编辑现有 JSON 文件，但不要用下面的示例覆盖已经生成的内容。

默认存储下，`translations/*.json` 保存自动译文。先在分片中搜索目标 `source`，保留 `version`、消息
标识和源码信息，只修改目标消息 `translations` 下的语言值。不要修改 `manifest.json`，也不要手工把
消息移动到另一个分片。以下分片示例对应不带 `comment` 的 `t('保存')`：

```json
{
  "version": 1,
  "messages": {
    "保存": {
      "source": "保存",
      "sourceLang": "zh-CN",
      "translations": {
        "en-US": "Save"
      }
    }
  }
}
```

SQLite 模式不适合直接编辑数据库，请使用 Provider 或 Agent + MCP。少量已确认措辞仍建议写入
`overrides.json`，这样可以提交并在不同电脑间保持一致。

`overrides.json` 使用便于审查的扁平 `rules` 保存人工决定。只写 `source` 时，译文对当前 Vite
应用内的所有同源文案生效：

```json
{
  "version": 2,
  "rules": [
    {
      "source": "保存",
      "translations": {
        "en-US": "Save"
      }
    }
  ]
}
```

同一句话只需要在部分文件采用不同译法时，为规则增加 `files`。路径必须是相对 Vite `root` 的
标准化 POSIX 路径，并与列表工具返回的 `source_file` 完全一致；不接受绝对路径、路径片段或 glob。
一个规则可以列出多个文件，以复用完全相同的审校决定：

```json
{
  "version": 2,
  "rules": [
    {
      "source": "保存",
      "files": ["src/editor/actions.ts", "src/editor/toolbar.ts"],
      "translations": {
        "en-US": "Save file"
      }
    },
    {
      "source": "保存",
      "comment": "保存状态",
      "files": ["src/status/panel.ts"],
      "translations": {
        "en-US": "Keep"
      }
    }
  ]
}
```

`comment` 与 `files` 可以单独使用，也可以组合。最终优先级从高到低是：文件 + `comment`、全局 +
`comment`、文件默认、全局默认、自动译文、源码回退。建议使用
[Agent + MCP](/ai-i18n/guide/advanced/ai-tools.md) 列出现有文案和精确路径，确认措辞后再写入；不要自行构造
语境标识。生成目录 `i18n/extracted/` 和 `i18n/locales/` 不接受人工编辑。

## 提交前检查

- 切换每一种支持语言，确认关键页面没有意外回退到源码文案；
- 确认占位符、代码和品牌名没有被误译；
- 运行 `vite build`；
- 遵循[生成文件与 Git](/ai-i18n/guide/basic/directory.md)的提交规则。



---
url: https://bosens-china.github.io/ai-i18n/guide/quality/typescript.md
---

# TypeScript 与生成声明

本页只说明 ai-i18n 为 TypeScript 项目增加的内容。通过 Vite 模板创建的项目可以继续使用模板
自带的 TypeScript 配置，不需要为了接入 ai-i18n 重写 `tsconfig`。

## 接入类型声明

首次启动 Vite Dev Server 或执行 Build 后，插件会在 Vite root 下生成声明文件。默认路径是：

```text
src/ai-i18n.d.ts
```

它位于 Vite 模板默认包含的 `src/` 中，因此通常不需要额外配置。业务源码也不应 import
这个 `.d.ts` 文件；正常导入 `virtual:ai-i18n`，或按需开启自动导入即可。

```ts
import { t, useI18n } from 'virtual:ai-i18n';
```

如果编辑器在文件生成后仍保留旧错误，先重启 TypeScript language service 或编辑器，再运行
项目已有的类型检查命令。

## 生成文件各自负责什么

### `ai-i18n.d.ts`

主声明适用于 Vanilla、Vue 和 React，除非显式设置 `dts: false`。它负责：

- 声明 `virtual:ai-i18n` 及当前框架可用的 Runtime API；
- 声明无需 import 的 `defineI18nMessages()` 编译宏；
- 开启 `autoImport: true` 后，为脚本中的自动导入 API 提供全局类型。

这个文件解决的是 TypeScript 脚本作用域中的类型问题。

### `ai-i18n.vue.d.ts`

Vue 模式同时开启 `autoImport: true` 时，还会在主声明旁生成：

```text
src/ai-i18n.d.ts
src/ai-i18n.vue.d.ts
```

第二个文件扩展 Vue 的组件类型，让 Vue language-tools（Volar）与 `vue-tsc` 识别 template
中的裸 `t()`。主声明会引用它，因此两个文件应保持相邻。

这个文件只是 template 的类型桥，不会向组件实例安装 method。即使编辑器能识别
`{{ t('保存') }}`，脚本中也不要改写成 `this.t()` 或 `this.$t()`。

生成声明由插件维护，不要手工修改。是否提交到 Git 以及其他生成文件的归属见
[生成文件与 Git](/ai-i18n/guide/basic/directory.md)。

## 显式导入与自动导入

| 使用方式                   | 脚本类型来源    | Vue template 类型来源                      |
| ---------------------- | --------- | -------------------------------------- |
| 从 `virtual:ai-i18n` 导入 | 主声明中的模块声明 | `<script setup>` 或 Options 的真实 binding |
| `autoImport: true`     | 主声明中的全局声明 | 相邻的 Vue template 类型桥                   |

两种模式都不需要 import `.d.ts` 文件。如何开启自动导入、Options 组件怎样暴露 template
binding，以及本地同名值的遮挡规则统一见[自动导入](/ai-i18n/guide/basic/auto-import.md)。

## 自定义声明路径

只有默认的 `src/ai-i18n.d.ts` 不适合项目目录结构时，才需要设置 `dts`。相对路径基于当前
Vite root；也可以使用绝对路径：

```ts title="vite.config.ts"
aiI18n({
  autoImport: true,
  dts: 'types/web-ai-i18n.d.ts',
});
```

Vue 自动导入模式会在同一目录生成：

```text
types/web-ai-i18n.d.ts
types/web-ai-i18n.vue.d.ts
```

自定义路径不在项目原有 TypeScript 检查范围内时，只需把该目录或两个文件加入实际检查应用
源码的 `include`。不要把文件路径写入 `compilerOptions.types`；该字段用于选择自动加载的
类型包，不用于包含项目内的声明文件。

如果目标位置已有不带 ai-i18n 生成标记的文件，插件会停止并保留原文件。修改 `dts` 路径或
设置 `dts: false` 后，请手工删除旧位置的主声明和相邻 Vue 声明。只有宿主项目自行维护
等价声明时，才建议关闭生成。

## Monorepo

每个独立 Vite build 应生成自己的声明文件，不要让多个应用写入同一路径。

应用私有的 workspace 子包需要使用自动导入时，可以把 `dts` 输出到应用与子包各自的
TypeScript 项目都能包含的位置。Vue 自动导入需要同时包含主声明与相邻的 `.vue.d.ts`。

可被多个应用或独立构建复用的共享包，优先显式导入 `virtual:ai-i18n`。这样共享包不会依赖
某个消费应用提供的全局声明。

## 常见类型问题

### 找不到 `virtual:ai-i18n`

先启动一次 Vite Dev Server 或执行 Build，确认主声明已经生成。默认路径被移动后，确认
新的 `dts` 路径仍在当前 TypeScript 项目的检查范围内。

### 找不到 `defineI18nMessages`

这个名字是由主声明提供的全局编译宏，不需要 import。确认 `ai-i18n.d.ts` 已生成并被当前
TypeScript 项目包含。

### Vue template 找不到 `t`

如果使用显式导入，确认 `<script setup>` 已导入 `t`，或普通 Options 组件已通过
`methods: { t }` 暴露 binding。

如果开启了自动导入，确认主声明旁同时存在 `.vue.d.ts`。两份文件都存在但编辑器仍报错时，
重启 Vue language service，再执行 `vue-tsc` 检查。

### Options API 中 `this` 没有正确类型

TypeScript 组件应使用 `defineComponent()`。如果项目关闭了模板自带的严格检查，至少确认
`noImplicitThis` 没有被关闭，否则 methods、computed 和 watch 中的 `this` 会退化为
`any`。

```ts
import { defineComponent } from 'vue';
import { i18nComputed } from 'virtual:ai-i18n';

export default defineComponent({
  computed: {
    ...i18nComputed(),
  },
});
```

### Options watch 参数被推断为 `any`

Vue 的 Options `watch` 类型不会根据被监听的 key 推断回调参数。请显式标注参数：

```ts
watch: {
  currentLang(next: string, previous: string) {
    console.log(previous, '->', next);
  },
},
```

### 移动声明后仍出现重复或过期类型

插件只维护当前配置指定的位置，无法推断曾经使用过的自定义路径。删除旧的主声明及其相邻
Vue 声明，然后重启类型服务。

## 运行类型检查

Vite 负责转译 TypeScript，不会替代完整的类型检查。项目已有 `type-check` 脚本时优先使用
项目脚本；Vue SFC 项目通常运行 `vue-tsc --noEmit`，React 或 Vanilla 项目通常运行
`tsc --noEmit`。



---
url: https://bosens-china.github.io/ai-i18n/guide/quality/eslint.md
---

# ESLint

`@ai-i18n/eslint-plugin` 用于尽早发现不可翻译的参数、内嵌静态 markup 的翻译源文、不会随语言
切换更新的文案，以及不必要的显式导入。它不会修改你的翻译文件。

## 安装


```sh [npm]
npm install -D eslint @ai-i18n/eslint-plugin@alpha
```

```sh [yarn]
yarn add -D eslint @ai-i18n/eslint-plugin@alpha
```

```sh [pnpm]
pnpm add -D eslint @ai-i18n/eslint-plugin@alpha
```

```sh [bun]
bun add -D eslint @ai-i18n/eslint-plugin@alpha
```

```sh [deno]
deno add -D npm:eslint npm:@ai-i18n/eslint-plugin@alpha
```

:::warning Alpha 阶段
预发布期间请显式安装 `@alpha`。插件支持 ESLint 9 和 10。
:::

pnpm monorepo 应将插件安装在实际加载 `eslint.config.*` 的 workspace 中。例如从仓库根目录加载
配置时，运行：

```sh
pnpm add -Dw @ai-i18n/eslint-plugin@alpha
```

Vue 项目还需要保留现有的 `eslint-plugin-vue`、`vue-eslint-parser` 和 `@vue/compiler-sfc`。

## 使用显式导入

未开启 ai-i18n 自动导入时，Vanilla 和 React 项目使用 `recommended`：

```js
// eslint.config.mjs
import aiI18n from '@ai-i18n/eslint-plugin';
import { defineConfig } from 'eslint/config';

export default defineConfig([...aiI18n.configs.recommended]);
```

Vue 项目使用 `vue`：

```js
export default defineConfig([...aiI18n.configs.vue]);
```

将这份配置与项目已有的 Vue Flat Config 一起使用。ai-i18n 不会替代 Vue 自身的解析器和规则。

## 使用自动导入

`aiI18n({ autoImport: true })` 时，选择与 Vite 框架模式相同的预设：

```js
// eslint.config.mjs
import aiI18n from '@ai-i18n/eslint-plugin';
import { defineConfig } from 'eslint/config';

export default defineConfig([
  ...aiI18n.configs['vanilla-auto-import'],
  // Vue：...aiI18n.configs['vue-auto-import']
  // React：...aiI18n.configs['react-auto-import']
]);
```

| 项目      | 使用的预设                 |
| ------- | --------------------- |
| Vanilla | `vanilla-auto-import` |
| Vue     | `vue-auto-import`     |
| React   | `react-auto-import`   |

这些预设会声明对应的 ai-i18n 全局 API，并检查其使用方式。生产配置和测试配置的 `autoImport`
值应保持一致。Vue 与 React preset 同时声明基础 Runtime API 和框架专属 API。

### Monorepo 子包

子包不需要因为被 Vite 应用消费而重复注册 `@ai-i18n/vite`。但 ESLint 配置取决于实际执行
lint 的位置：

- 仓库根 `eslint.config.*` 已覆盖 `packages/**` 时，只需在根配置使用一次对应 preset。
- 子包拥有独立 `eslint.config.*` 或独立 lint 命令时，该配置也必须引入相同 preset。
- 开启自动导入时，子包使用的 preset 必须与消费它的 Vite build 框架模式一致。

可复用子包更适合显式导入 `virtual:ai-i18n` 并使用普通 `vue`、`recommended` 等显式导入
preset，避免绑定到某个应用的自动导入约定。

## JavaScript 项目的路径别名

纯 JavaScript 项目不需要为了 ESLint 路径解析额外创建 `tsconfig.json`。如果项目已在 Vite
中配置对象形式的本地源码 alias，可以导出同一个对象，并传给 ai-i18n 的 ESLint settings：

```js
// aliases.js
import { fileURLToPath } from 'node:url';

export const alias = {
  '@': fileURLToPath(new URL('./src', import.meta.url)),
};
```

```js
// vite.config.js
import { defineConfig } from 'vite';
import { alias } from './aliases.js';

export default defineConfig({
  resolve: { alias },
});
```

```js
// eslint.config.js
import aiI18n from '@ai-i18n/eslint-plugin';
import { defineConfig } from 'eslint/config';
import { alias } from './aliases.js';

export default defineConfig([
  ...aiI18n.configs.recommended,
  {
    settings: {
      'ai-i18n': { alias },
    },
  },
]);
```

replacement 必须使用绝对路径。显式 alias 的匹配结果优先；未匹配时，插件会继续查找
`tsconfig.json` 或 `jsconfig.json`。插件不会加载或执行 `vite.config.*`。支持范围与查找顺序见
[ESLint 规则参考](/ai-i18n/guide/quality/eslint-rules.md)。

## 常见问题

### 为什么 `t()` 参数报错

`t()` 只接受能在构建时确定的文案。优先使用字符串、静态 `const` 或条件表达式：

```ts
t('保存');

const label = '取消';
t(label);

t(canSubmit ? '提交' : '返回');
```

需要按索引读取一组文案时，使用 `defineI18nMessages()`。完整示例见
[通用文案写法](/ai-i18n/guide/basic/static-analysis/common.md)。

### 为什么 React 组件中的 `t()` 提示不会更新

React 组件要使用 `useI18n()` 返回的 `t`，不能在渲染路径直接使用顶层 `t`：

```tsx
function SaveButton() {
  const { t } = useI18n();
  return <button>{t('保存')}</button>;
}
```

Vue template、render 与 computed 可以直接使用顶层 `t()`，它会追踪 Vue adapter
revision。不要在模块初始化、state、storage 或业务数据中长期保存已经翻译的字符串。Vue
setup 中需要预先声明响应式展示文案时，使用 `tRef()`。纯 Options 组件使用
`tComputed()` 时，应把它直接写成 `computed` 属性值；放在 `data()`、template、render
或模块级变量中会得到 getter 而不是译文，规则会报告该用法。纯 Options `data()` 直接保存
`t()` 结果也只会保留初始化译文，应改用 `tComputed()` 或执行时调用 `t()`。

关闭自动导入时，纯 Options template 直接调用显式导入的 `t()`，需要在 `methods` 中建立
`t` binding；规则也识别改名导入映射。开启自动导入后，无需 `methods: { t }`，规则会直接
检查 script 和 template 中未绑定的 `t()`。本地同名 method 仍然遮挡自动导入。脚本内使用
词法作用域中的 `t()`；`this.t()` 与 `this.$t()` 不属于静态提取写法。

`getLang()` 与 `getLangLoadState()` 同样返回快照。组件展示当前语言或加载状态时，使用
Composition API 的 `useI18n()`；纯 Options 组件则在 `computed` 中展开
`...i18nComputed()`。普通 `setup()` 或 Options `data()` 保存快照会收到提示；
`i18nComputed()` 放在 setup、data、methods、render 或 template 也会提示改回根
`computed`。在 action、事件处理器或工具函数中按需读取 Runtime 快照不受限制。

### 为什么显式导入提示多余

自动导入预设默认兼容显式导入。如果团队希望统一使用自动导入，可额外开启
`no-redundant-auto-import`，并执行 `eslint --fix`。规则选项和适用范围见
[ESLint 规则参考](/ai-i18n/guide/quality/eslint-rules.md)。

## 诊断语言

ESLint 与 Vite 的开发者诊断默认按系统时区显示中文或英文。需要固定语言时，设置：

```text
AI_I18N_DIAGNOSTIC_LOCALE=zh-CN
AI_I18N_DIAGNOSTIC_LOCALE=en-US
```

设置为 `auto` 可恢复自动选择。该环境变量只影响提示文字，不影响规则结果。

## 下一步

- [ESLint 规则参考](/ai-i18n/guide/quality/eslint-rules.md)：按需调整规则选项和路径解析。
- [测试（Vitest）](/ai-i18n/guide/quality/testing.md)：在测试环境中使用 ai-i18n。



---
url: https://bosens-china.github.io/ai-i18n/guide/quality/eslint-rules.md
---

# ESLint 规则参考

本页面向需要自定义 ESLint 行为的项目。常规接入请先阅读 [ESLint](/ai-i18n/guide/quality/eslint.md)。

## 规则总览

官方预设已经注册适用规则。需要调整默认值时，先引入对应预设，再覆盖目标规则。下面以
`recommended` 为例：

```js
import aiI18n from '@ai-i18n/eslint-plugin';
import { defineConfig } from 'eslint/config';

export default defineConfig([
  ...aiI18n.configs.recommended,
  {
    rules: {
      'ai-i18n/static-candidate-limit': ['warn', { maxStaticCandidates: 2000 }],
    },
  },
]);
```

| 规则                              | 默认级别    | 范围        | 用途                           |
| ------------------------------- | ------- | --------- | ---------------------------- |
| `t-static-args`                 | error   | 通用        | 拒绝无法静态提取或不推荐的翻译调用参数。         |
| `no-embedded-markup`            | warning | 通用        | 避免让静态 HTML/SVG 结构进入翻译源文。     |
| `no-eager-translation`          | warning | 通用，Vue 扩展 | 避免在初始化阶段长期保存译后字符串。           |
| `no-unsubscribed-runtime-state` | warning | 通用，框架扩展   | 避免缓存或渲染非响应式语言状态快照。           |
| `no-unsubscribed-t`             | warning | Vue、React | 检查组件渲染和 Vue 响应式翻译 API 的生命周期。 |
| `static-candidate-limit`        | warning | 通用        | 文案候选数量过大时发出警告。               |
| `no-redundant-auto-import`      | 默认关闭    | 自动导入项目    | 删除已经由自动导入提供的同名显式导入。          |

## 通用规则

### `t-static-args`

检查 `t()`、Vue `tRef()`、`tComputed()`，以及 `useI18n()` 返回的 `t`。source 必须能在构建
阶段确定；options 必须是仅包含 `comment` 的静态对象。动态字符串、不支持的调用形式和不推荐的
集合成员引用会报错。

### `no-embedded-markup`

检查 `t()`、tagged template、Vue `tRef()`、`tComputed()` 以及 `useI18n()` 返回的
`t`。规则分析最终可提取 source；直接字符串、静态 `const`、条件候选和文案树共用同一口径。

下列写法会收到 warning：

```ts
t`<div>温度：<span style="color:${color}">${temp}℃</span></div>`;
```

处理原则、推荐写法和 HTML 插值的安全边界见
[通用文案写法](/ai-i18n/guide/basic/static-analysis/common.md#支持的参数)。规则不限制长文案、多行文案、
占位符数量、条件候选或文案树规模，也不检查仅在插值运行时值中出现的 HTML。
第一版不识别 JSON、URL、SQL 或 Shell，也不把纯 Markdown 语法视为 markup。

### `no-eager-translation`

检查模块初始化或组件初始化期间保存的 `t()` 结果。长期保存的译文不会随语言切换更新。普通
函数和 getter 在执行时重新调用 `t()`，因此可以使用。Vue `setup()` 与 Options `data()` 的
额外检查见下方 Vue Tab。

这条规则不代表文案无法提取，而是提醒“提取成功”和“切换语言后刷新”是两件事。例如图表配置、
路由标题等长生命周期对象，不要在模块加载时保存译文快照：

```ts
// warning：模块加载时只翻译一次
export const chartOptions = {
  title: { text: t('销量') },
};

// 允许：在创建或重建图表时读取当前语言
export function createChartOptions() {
  return {
    title: { text: t('销量') },
  };
}
```

工厂函数需要在首次渲染和语言变化后重新调用；如果调用方仍只在初始化时执行一次，结果仍然不会
刷新。有限的集中式标题集合可以先声明文案，再在实际取值时翻译：

```ts
const ROUTE_TITLES = defineI18nMessages({
  detail: '详情',
  edit: '编辑',
});

export function getRouteTitle(name: keyof typeof ROUTE_TITLES) {
  return t(ROUTE_TITLES[name]);
}
```

Vue setup 中需要长期持有单个译文时使用 `tRef()`；纯 Options API 在根 `computed` 中使用
`tComputed()`。模板、render、computed getter、事件处理器和普通延迟函数可以在执行时直接
调用 `t()`。

部分第三方配置允许把文案写成函数，例如表单校验规则。此时优先使用第三方 API 提供的延迟
回调，不要为了消除 warning 改回固定的源语言字面量：

```ts
const passwordRules = {
  userPassword: {
    required: true,
    // warning：初始化时保存译文快照
    message: t('请输入旧密码'),
  },
};

const lazyPasswordRules = {
  userPassword: {
    required: true,
    // 允许：校验产生错误时读取当前语言
    message: () => t('请输入旧密码'),
  },
};
```

只有第三方 API 明确支持函数值时才能使用这种写法；否则使用工厂函数或框架提供的响应式 API。

### `no-unsubscribed-runtime-state`

检查 `getLang()` 与 `getLangLoadState()` 返回的快照。模块顶层不能缓存这些值，组件渲染也应
改用框架提供的响应式状态。事件处理器、action、普通工具函数和即时日志可以按需读取。

### `static-candidate-limit`

检查单个翻译调用展开后的 source 与 options 组合。默认超过 1000 个静态候选时发出 warning。
确实存在大型有限集合时，可以提高阈值：

```js
'ai-i18n/static-candidate-limit': [
  'warn',
  { maxStaticCandidates: 2000 },
],
```

这项设置只影响 ESLint 警告，不改变 Vite 的翻译结果。

### `no-redundant-auto-import`

自动导入预设默认不启用该规则。启用后，它会报告 `virtual:ai-i18n` 中已经由当前框架自动注入的
同名值导入，并支持 `eslint --fix`。改名导入、命名空间导入和类型导入会保留；import 内有注释
时只报告，不自动修改。

## 框架规则

新项目优先使用与 Vite 框架模式一致的预设。下面按框架说明额外检查，并列出自动导入预设的
完整规则配置。框架自动导入 API 见 [自动导入](/ai-i18n/guide/basic/auto-import.md)。


**Vanilla**

自动导入项目使用 `vanilla-auto-import`。该预设的规则配置如下：
```js
{
  rules: {
    'ai-i18n/t-static-args': ['error', { autoImport: ['t'] }],
    'ai-i18n/no-embedded-markup': ['warn', { autoImport: ['t'] }],
    'ai-i18n/no-eager-translation': ['warn', { autoImport: ['t'] }],
    'ai-i18n/no-unsubscribed-runtime-state': [
      'warn',
      { autoImport: ['getLang', 'getLangLoadState'] },
    ],
    'ai-i18n/static-candidate-limit': ['warn', { autoImport: ['t'] }],
  },
}
```
Vanilla 只使用通用规则。它没有组件渲染生命周期，因此 `vanilla-auto-import` 不启用
`no-unsubscribed-t`。
启用可选的 `no-redundant-auto-import` 时，传入 Vanilla 注入的完整 Runtime API：
```js
{
  autoImport: [
    't',
    'setLang',
    'getLang',
    'getLangs',
    'getLangLoadState',
    'subscribe',
  ],
}
```


**Vue**

自动导入项目使用 `vue-auto-import`。该预设的规则配置如下：
```js
{
  rules: {
    'ai-i18n/t-static-args': [
      'error',
      { autoImport: ['t', 'tRef', 'tComputed', 'useI18n'] },
    ],
    'ai-i18n/no-embedded-markup': [
      'warn',
      { autoImport: ['t', 'tRef', 'tComputed', 'useI18n'] },
    ],
    'ai-i18n/no-eager-translation': [
      'warn',
      {
        autoImport: ['t', 'tRef', 'tComputed', 'useI18n'],
        framework: 'vue',
      },
    ],
    'ai-i18n/no-unsubscribed-runtime-state': [
      'warn',
      {
        autoImport: ['getLang', 'getLangLoadState', 'i18nComputed'],
        framework: 'vue',
      },
    ],
    'ai-i18n/no-unsubscribed-t': [
      'warn',
      {
        autoImport: ['t', 'tRef', 'tComputed', 'useI18n'],
        framework: 'vue',
      },
    ],
    'ai-i18n/static-candidate-limit': [
      'warn',
      { autoImport: ['t', 'tRef', 'tComputed', 'useI18n'] },
    ],
  },
}
```
Vue template、render 和 computed 可以直接调用词法作用域中的顶层 `t()`。规则还会检查以下
Composition API 与 Options API 生命周期问题：
| 写法或位置                                            | 触发规则                            | 推荐写法                                                                       |
| ------------------------------------------------ | ------------------------------- | -------------------------------------------------------------------------- |
| `setup()` 保存 `t()` 结果                            | `no-eager-translation`          | 使用 `tRef()`，或在函数执行时调用 `t()`。                                               |
| Options `data()` 保存 `t()` 结果                     | `no-eager-translation`          | 使用根 `computed` 中的 `tComputed()`。                                           |
| Options `computed/data/methods` 或渲染期间调用 `tRef()` | `no-unsubscribed-t`             | setup 使用 `tRef()`；computed/data 改为根 computed 的 `tComputed()`；其余位置调用 `t()`。 |
| `tComputed()` 未直接作为根 `computed` 属性值              | `no-unsubscribed-t`             | 写成 `computed: { label: tComputed('保存') }`。                                 |
| setup、Options 或渲染路径保存 Runtime 状态快照               | `no-unsubscribed-runtime-state` | 使用 `useI18n()` 或 `i18nComputed()`。                                         |
| `i18nComputed()` 未直接展开到根 `computed`              | `no-unsubscribed-runtime-state` | 写成 `computed: { ...i18nComputed() }`。                                      |
| 使用组件实例成员 `this.t()` 或 `this.$t()`                | `no-unsubscribed-t`             | 调用词法作用域中的 `t()`。                                                           |
自动导入模式下，纯 Options template 可以直接使用未绑定的 `t()`；本地同名值仍然遮挡。关闭
自动导入时，`methods: { t }` 或 `methods: { t: translate }` 必须解析到 ai-i18n Runtime
`t`，才能作为 template binding。
启用可选的 `no-redundant-auto-import` 时，传入 Vue 注入的完整 API：
```js
{
  autoImport: [
    'useI18n',
    't',
    'setLang',
    'getLang',
    'getLangs',
    'getLangLoadState',
    'subscribe',
    'tRef',
    'i18nComputed',
    'tComputed',
  ],
}
```


**React**

自动导入项目使用 `react-auto-import`。该预设的规则配置如下：
```js
{
  rules: {
    'ai-i18n/t-static-args': [
      'error',
      { autoImport: ['t', 'useI18n'] },
    ],
    'ai-i18n/no-embedded-markup': [
      'warn',
      { autoImport: ['t', 'useI18n'] },
    ],
    'ai-i18n/no-eager-translation': [
      'warn',
      { autoImport: ['t', 'useI18n'] },
    ],
    'ai-i18n/no-unsubscribed-runtime-state': [
      'warn',
      { autoImport: ['getLang', 'getLangLoadState'] },
    ],
    'ai-i18n/no-unsubscribed-t': [
      'warn',
      { autoImport: ['t', 'useI18n'] },
    ],
    'ai-i18n/static-candidate-limit': [
      'warn',
      { autoImport: ['t', 'useI18n'] },
    ],
  },
}
```
React 在通用规则之外增加组件订阅检查：
| 写法或位置                      | 触发规则                            | 推荐写法                     |
| -------------------------- | ------------------------------- | ------------------------ |
| JSX / TSX 渲染路径直接调用顶层 `t()` | `no-unsubscribed-t`             | 使用 `useI18n()` 返回的 `t`。  |
| 渲染路径读取 Runtime 状态快照        | `no-unsubscribed-runtime-state` | 使用 `useI18n()` 返回的响应式状态。 |
| 事件处理器或普通延迟函数调用顶层 `t()`     | 不触发                             | 保持按需读取。                  |
启用可选的 `no-redundant-auto-import` 时，传入 React 注入的完整 API：
```js
{
  autoImport: [
    'useI18n',
    't',
    'setLang',
    'getLang',
    'getLangs',
    'getLangLoadState',
    'subscribe',
  ],
}
```


## 规则选项

| 选项                    | 适用规则与行为                                                                                                          |
| --------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `autoImport`          | 六条检查规则接受布尔值或各自支持的 API 数组；`no-redundant-auto-import` 只接受非空 API 数组。                                                |
| `framework`           | `no-eager-translation` 接受 `vue`；`no-unsubscribed-t` 与 `no-unsubscribed-runtime-state` 接受 `vue` 或 `react`。        |
| `tsconfigPath`        | 仅适用于 `t-static-args`、`no-embedded-markup`、`no-eager-translation`、`no-unsubscribed-t` 和 `static-candidate-limit`。 |
| `maxStaticCandidates` | 仅适用于 `static-candidate-limit`，必须是正整数。                                                                            |

翻译调用规则中的 `autoImport: true` 是兼容性简写，只启用 `t` 与 `useI18n`，不包含 Vue 专属的
`tRef` 和 `tComputed`。状态快照规则中的 `autoImport: true` 会启用 `getLang`、
`getLangLoadState` 与 `i18nComputed`。框架项目应优先使用预设；手动配置时使用 Tabs 中的明确
API 数组。

`no-eager-translation`、`no-unsubscribed-t` 和 `no-unsubscribed-runtime-state` 只判断当前
文件内可以确定的生命周期问题，不追踪跨文件 store 数据流。

## 路径别名与项目配置

项目可以通过共享 settings 显式提供本地源码 alias。显式 alias 拥有最高优先级，适合只在
Vite `resolve.alias` 中配置别名的 JavaScript 项目：

```js
import { fileURLToPath } from 'node:url';

export default [
  {
    settings: {
      'ai-i18n': {
        alias: {
          '@': fileURLToPath(new URL('./src', import.meta.url)),
        },
      },
    },
  },
];
```

第一版支持字符串到字符串的对象形式。replacement 必须使用绝对路径，并指向项目本地源码。
暂不支持 Vite 的数组形式、正则 `find`、`customResolver` 或 resolver plugin。ESLint 不会加载
或执行 `vite.config.*`；需要与 Vite 保持一致时，建议让两份配置导入同一个 alias 对象。

显式 alias 未匹配当前导入时，规则会从正在检查的文件向上寻找最近的 `tsconfig.json` 或
`jsconfig.json`。同一目录同时存在两者时，优先使用 `tsconfig.json`。纯 JavaScript 项目可以
直接使用 `jsconfig.json`：

```json
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["src/**/*.js", "src/**/*.jsx"]
}
```

项目使用非标准配置名、项目引用或特殊工作目录时，可以指定入口：

```js
'ai-i18n/t-static-args': [
  'error',
  { tsconfigPath: './tsconfig.json' },
],
```

`tsconfigPath` 路径以 ESLint 的工作目录为基准，并覆盖自动发现入口。无论使用
`tsconfig.json` 还是 `jsconfig.json`，插件都会解析 `extends`、项目 references 以及
`files`、`include`、`exclude`。该选项沿用现有名称，也可以直接指向 `jsconfig.json`。

Vue SFC 必须被所选项目配置的 `files` 或 `include` 显式覆盖。例如：

```json
{
  "include": ["src/**/*.ts", "src/**/*.vue"]
}
```



---
url: https://bosens-china.github.io/ai-i18n/guide/quality/testing.md
---

# 测试（Vitest）

在 `vitest.config.ts` 中使用 `aiI18nVitest()`，即可测试导入 `virtual:ai-i18n` 的业务模块，无需
手写 alias 或 mock。测试环境不执行自动翻译，也不会修改项目中的翻译文件。

如果 Vitest 输出“仅支持浏览器 Runtime，已跳过 SSR 转换/注入”，说明测试配置加载了生产用的
`aiI18n()`。不要忽略或静默过滤该提示；从 `@ai-i18n/vite/vitest` 改用
`aiI18nVitest()`，并确保同一测试配置只注册其中一个插件。

它支持 `t()`、`useI18n()`、Vue `tRef()`、纯 Options 的 `i18nComputed()` /
`tComputed()`、消息集合宏和自动导入。测试配置的 `autoImport` 应与正式 Vite 配置保持一致。
Jest 或直接 Node.js 执行不会处理消息集合宏，请改用 Vitest 配置或避免执行包含宏的源码。

## 快速开始


**React**

```ts
// vitest.config.ts
import { aiI18nVitest } from '@ai-i18n/vite/vitest';
import react from '@vitejs/plugin-react';
import { defineConfig } from 'vitest/config';

export default defineConfig({
  plugins: [
    aiI18nVitest({
      sourceLang: 'zh-CN', // 测试 Runtime 固定回退的源码语言
      // value 是语言标识，label 是组件中展示的名称。
      locales: [
        { value: 'zh-CN', label: '中文' },
        { value: 'en-US', label: 'English' },
      ],
      autoImport: true, // 仅当正式 Vite 配置也开启自动导入时保持一致
    }),
    react(), // 提供 React 转换，并让测试插件自动识别 React 模式
  ],
});
```


**Vue**

Vue 项目保留自己的 Vite Vue 插件：
```ts
// vitest.config.ts
import { aiI18nVitest } from '@ai-i18n/vite/vitest';
import vue from '@vitejs/plugin-vue';
import { defineConfig } from 'vitest/config';

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


**Vanilla JS**

Vanilla 项目不需要框架插件：
```ts
// vitest.config.ts
import { aiI18nVitest } from '@ai-i18n/vite/vitest';
import { defineConfig } from 'vitest/config';

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


保留项目原有的 Vue 或 React Vite 插件。大多数项目不需要设置 `framework`；只有自定义构建环境
无法识别框架时，才显式传入该选项。

## 与正式配置共享 options

`AiI18nVitestOptions` 是 `AiI18nOptions` 的子集，只保留 `sourceLang`、`defaultLang`、
`locales`、`framework`、`persist`、`autoImport`。把这部分抽成共享文件，`vite.config.ts`
与 `vitest.config.ts` 各自引用，语言列表和运行时策略只需要改一处：

```ts
// ai-i18n.options.ts
export const aiI18nOptions = {
  sourceLang: 'zh-CN', // 源码文案使用的语言
  defaultLang: 'zh-CN', // 没有有效持久化值时的初始语言
  // value 是语言标识，label 是组件中展示的名称。
  locales: [
    { value: 'zh-CN', label: '中文' },
    { value: 'en-US', label: 'English' },
  ],
  persist: { key: 'app-lang' }, // 使用指定 localStorage key 保存语言偏好
  autoImport: true, // 两种环境使用同一模式化自动导入契约
} as const;
```

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

export default defineConfig({
  plugins: [
    aiI18n(aiI18nOptions),
    react(), // 保留宿主 React 转换
  ],
});
```

```ts
// vitest.config.ts
import { aiI18nVitest } from '@ai-i18n/vite/vitest';
import { aiI18nOptions } from './ai-i18n.options';

export default defineConfig({
  plugins: [
    aiI18nVitest(aiI18nOptions),
    react(), // 保留宿主 React 转换
  ],
});
```

`html`、`loading`、`cache`、`provider`、`directory`、`dts` 等构建期字段不属于
`AiI18nVitestOptions`；直接把完整的 `aiI18n()` 配置对象传给 `aiI18nVitest()` 会被 TypeScript
拒绝多余字段，按需只挑测试需要的子集传入即可。

## 测试环境的能力范围

| 能力                         | 测试环境行为                                                   |
| -------------------------- | -------------------------------------------------------- |
| `t(source)` / `` t`...` `` | 可用。测试 Runtime 没有加载任何目标语言译文，因此固定返回 source 文案。             |
| `setLang(value)`           | 可用，可用于测试语言切换触发的重渲染，以及 `persist` 写入 localStorage。         |
| `useI18n()`                | Vue / React 模式下可用；字段契约一致，但测试 Runtime 的语言加载状态固定为 `idle`。  |
| `tRef()`                   | 仅 Vue 模式可用；返回响应式 source fallback Ref，与生产环境保持相同 API 形状。   |
| `i18nComputed()`           | 仅 Vue 模式可用；返回与生产一致的 Options computed 配置。                 |
| `tComputed()`              | 仅 Vue 模式可用；返回 source fallback 的 Options computed getter。 |
| 自动导入                       | 仅在 `autoImport: true` 时注入，API 集合与同一框架模式的生产插件一致。          |
| 翻译文件与自动翻译                  | 不会读取、修改或调用。                                              |
| Provider / AI 自动翻译         | 不会调用；`provider` 不属于 `AiI18nVitestOptions`。               |

由于没有加载任何目标语言译文，`t('保存')` 始终返回 `"保存"`，即使调用过
`await setLang('en-US')` 之后也是如此。可以把这类测试理解为契约测试——只断言组件确实调用了
`t()` 并渲染出结果，不断言具体译文内容。

`loading` 不属于 `AiI18nVitestOptions`，测试 Runtime 不创建语言 chunk loader。
`getLangLoadState()` 以及 `useI18n()` 的 loading/error 字段仍存在，但固定为 `idle`；真实
loading/error 变化应由应用自己的抽象单测或生产 Vite 集成测试覆盖。

单元测试不应断言某个语言一定翻译为特定字词。译文质量通过人工审校或
[AI 翻译](/ai-i18n/guide/advanced/ai-translation.md)流程确认；CI 可以额外运行一次真实的 `vite build`。

## 常见问题

**测试环境需要先跑过 `vite build` 或存在 Translation Memory 吗？**
不需要。测试插件不依赖项目中的翻译文件，也能正常解析 `virtual:ai-i18n`。

**能不能在同一个 `vitest.config.ts` 里同时注册 `aiI18n()` 和 `aiI18nVitest()`？**
不要这样做。两者都会尝试解析 `virtual:ai-i18n`，只注册 `aiI18nVitest()` 即可。

**端到端测试（Playwright 等）呢？**
`aiI18nVitest()` 只覆盖 Vitest 场景。端到端测试应运行真实的 `vite dev` 或 `vite build`，
以覆盖实际的语言切换和翻译结果。



---
url: https://bosens-china.github.io/ai-i18n/guide/advanced/ai-translation.md
---

# AI 翻译

ai-i18n 提供两种补译方式：

| 方式                                                 | 适用场景                       |
| -------------------------------------------------- | -------------------------- |
| OpenAI Provider                                    | 希望在 Vite 开发或构建时自动补齐缺失译文。   |
| [Agent + MCP](/ai-i18n/guide/advanced/ai-tools.md) | 希望由 AI 编码工具在明确指令下检查、补译和审校。 |

本页介绍 OpenAI-compatible Provider。未配置 Provider 时，ai-i18n 仍会提取文案和生成语言包；
缺失译文会显示源码文案。

## 安装


```sh [npm]
npm add @ai-i18n/openai@alpha
```

```sh [yarn]
yarn add @ai-i18n/openai@alpha
```

```sh [pnpm]
pnpm add @ai-i18n/openai@alpha
```

```sh [bun]
bun add @ai-i18n/openai@alpha
```

```sh [deno]
deno add npm:@ai-i18n/openai@alpha
```

:::warning Alpha 阶段
预发布期间请显式安装 `@alpha`。`npm` 的 `latest` 标签不代表当前推荐的 alpha 版本。
:::

## 最小配置

Provider 在 Vite 的 Node.js 进程中运行。将密钥保留在服务端配置中，不要使用 `VITE_` 前缀，也不要
在浏览器业务代码中导入 Provider。

```ts
// vite.config.ts
import { openAI } from '@ai-i18n/openai';
import { aiI18n } from '@ai-i18n/vite';
import { defineConfig, loadEnv } from 'vite';

function required(value: string | undefined, name: string): string {
  if (!value) throw new Error(`Missing ${name}`);
  return value;
}

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), 'AI_');

  return {
    plugins: [
      aiI18n({
        sourceLang: 'zh-CN',
        locales: [
          { value: 'zh-CN', label: '中文' },
          { value: 'en-US', label: 'English' },
        ],
        provider: {
          translator: openAI({
            baseURL: required(env.AI_BASE_URL, 'AI_BASE_URL'),
            model: required(env.AI_MODEL, 'AI_MODEL'),
            apiKey: env.AI_API_KEY,
            systemPrompt: `
你负责翻译面向开发者的 Web 产品界面。
- 使用自然、简洁的目标语言，按钮优先使用动词。
- 保留 ai-i18n、Vite、Vue、React、代码、URL、变量名和占位符。
- 结合 comment 判断文案语境。
            `.trim(),
          }),
        },
      }),
    ],
  };
});
```

`.env.local` 示例：

```dotenv
AI_BASE_URL=https://example.com/v1
AI_MODEL=model-name
AI_API_KEY=replace-me
```

本地无认证模型可以省略 `AI_API_KEY`。

## 审查模型日志

日志默认关闭。设置 `provider.logging: true` 后，OpenAI Provider 在 Vite 项目根目录的 `logs/` 生成
普通文本日志。日志用 `batchId` 串联模型输入、模型输出、校验、Vite 状态应用与持久化结果；并发
批次不会串号。

`provider.logging` 也可直接设置为相对 Vite root 或绝对路径的目录字符串。

如何开关、逐块阅读、定位失败、交给 AI Agent 分析，以及 Git 忽略和安全边界，见
[LLM 日志与排障](/ai-i18n/guide/advanced/llm-logs.md)。

## 编写翻译提示词

提示词只需说明产品语境、语气和固定术语。推荐使用短规则：

- 说明产品面向谁，例如开发者工具、消费应用或后台系统；
- 规定按钮、错误提示和帮助文案的语言风格；
- 列出必须保持不变的品牌名、代码、URL 和占位符；
- 列出团队已确认的术语；
- 要求优先参考 `comment` 消除歧义。

不要在提示词中放入 API 密钥、内部地址或会频繁变化的业务信息。文案本身的具体语境应写在
`t(source, { comment })` 中。

## 验证结果与失败处理

Provider 只补齐缺失译文。翻译失败时，页面继续显示源码文案，不会阻塞本地开发。提交前运行一次完整
Build，并检查关键页面和固定术语。

需要让 CI 在翻译请求失败或仍有缺失译文时停止构建，可以设置 `provider.strict: true`。批次大小、
并发、日志和刷新策略见 [`AiI18nProviderOptions`](/ai-i18n/api/vite/type-aliases/ai-i18n-provider-options.md)。
重试与超时由具体 Translator 或 Provider SDK 配置；OpenAI-compatible Provider 的字段见
[`OpenAIOptions`](/ai-i18n/api/openai/interfaces/open-ai-options.md)。

Provider 的模型、`baseURL`、温度或提示词变化时，插件默认继续复用历史自动译文，不会尝试分析
Translator 内部配置。需要让新配置刷新一次时，使用 `provider.cache: 'fresh'`；本进程生成的新结果仍会
立即缓存，因此 Dev/HMR 不会重复请求。该选项只影响 Provider，不影响 MCP 或 AI Agent。完整配置见
[Translation Memory](/ai-i18n/guide/advanced/translation-memory.md)。

## 使用其他模型服务

只要服务兼容 OpenAI API，就可以修改 `baseURL` 和 `model` 使用它。若需要接入其他 SDK，请实现
[`Translator`](/ai-i18n/api/vite/type-aliases/translator.md)。该 API 说明了输入、输出和错误处理约束。

人工确认译文、处理同一句话的不同语境，以及提交规则见[补译与审校](/ai-i18n/guide/basic/translations.md)。



---
url: https://bosens-china.github.io/ai-i18n/guide/advanced/llm-logs.md
---

# LLM 日志与排障

OpenAI Provider 可以把每个翻译批次的模型输入、模型输出、校验和持久化状态写成普通文本日志。
这些日志适合人工审查，也可以交给 AI Agent 判断问题发生在哪个环节。

## 开启或关闭日志

日志默认关闭。需要排障或审查时，只需配置 `provider.logging`：

```ts
aiI18n({
  sourceLang: 'zh-CN',
  locales,
  provider: {
    translator: openAI({
      baseURL: process.env.AI_BASE_URL!,
      apiKey: process.env.AI_API_KEY,
      model: process.env.AI_MODEL!,
    }),
    logging: true,
  },
});
```

省略或设置 `provider.logging: false` 时，当前 Vite Dev 或 Build 进程不会创建、追加日志，也不会
创建默认的 `logs/` 目录；翻译、提取、缓存和持久化照常执行。

`logging: true` 写入 Vite 项目根目录下的 `logs/`。也可以直接用字符串指定目录：

```ts
provider: {
  translator,
  logging: 'diagnostics/llm', // 相对 Vite root
}
```

相对字符串基于 Vite root 解析；绝对字符串保持不变。空字符串或只包含空白的字符串是无效配置，
插件会在启动时报告双语错误。日志开关没有 OpenAI Provider 级的第二套优先级。

## 日志文件生命周期

一个 `openAI()` Translator 实例在每个已解析目录中使用一个日志文件，文件名包含本地日期、时间、
PID 和进程序号：

```text
2026-08-06_13-46-44-834-p65013-1.log
```

- 普通 Build 每次创建新的 Translator，因此通常生成一个新文件。
- 同一 Dev、HMR 或 Build Watch 进程复用 Translator，后续批次继续追加到同一文件。
- 日志写入失败只警告一次，不会让翻译或 Build 失败。

## 按 batchId 阅读

同一翻译批次的每个日志块都带有相同 `batchId`。排障时先找到失败文案对应的 REQUEST 或
BATCH FAILED，再沿相同 ID 阅读：

```text
BATCH SCHEDULED
REQUEST
RESPONSE
VALIDATION
STATE APPLIED
PERSISTED
```

| 日志块               | 重点检查                                                 |
| ----------------- | ---------------------------------------------------- |
| `BATCH SCHEDULED` | 目标语言和消息数量是否符合预期。                                     |
| `REQUEST`         | `PARAMETERS`、`SYSTEM`、`USER` 是否包含正确模型参数和提示词。         |
| `RESPONSE`        | `REASONING`、`ASSISTANT`、finish reason、扩展字段与原始 usage。 |
| `VALIDATION`      | Provider 是否成功解析并校验全部语言和数组下标。                         |
| `STATE APPLIED`   | 结果是否进入当前 Vite ProjectState，以及影响的模块数量。                |
| `PERSISTED`       | 包含该批结果的文件与 Translation Memory 是否写入成功。                |
| `BATCH FAILED`    | Translator、输出校验或后续批次处理的失败原因。                         |
| `TRANSPORT ERROR` | 请求地址、状态、耗时与 SDK 暴露的网络错误。                             |

并发批次可能交错写入同一个文件，所以不要只按相邻行判断请求与响应；始终按 `batchId` 关联。

## 常见定位方式

- 有 REQUEST、没有 RESPONSE：优先检查超时、网络、认证、模型名与服务端错误。
- 有 RESPONSE、随后 BATCH FAILED：检查 assistant JSON、目标语言键、数组长度和占位符。
- 有 VALIDATION、没有 STATE APPLIED：检查 Vite 是否已有更新的同 message 请求，或状态应用错误。
- 有 STATE APPLIED、没有 PERSISTED：结合 Build/Dev 终端错误检查目录权限、文件冲突或存储失败。
- 已有 PERSISTED 但页面不更新：转向 Runtime 注册、当前语言、HMR 或 locale 加载排障。

给 AI Agent 排障时，提供相关日志文件并要求它先按 `batchId` 汇总上述阶段，再结合终端错误判断。日志
保留 SDK 实际暴露的 system/user messages、reasoning、assistant content、usage 和扩展字段，但不是
逐字节 HTTP 抓包；服务端或 SDK 没有暴露的数据无法补记。

## 安全与 Git 忽略

日志包含待翻译业务文案、完整提示词和模型输出，不应提交到版本库。至少加入：

```text
logs/
*.log
```

使用自定义目录时也要忽略该目录。Provider 会脱敏显式 API key，OpenAI SDK 会脱敏常见认证
Header；提交或分享日志前仍应人工检查业务敏感信息。



---
url: https://bosens-china.github.io/ai-i18n/guide/advanced/translation-memory.md
---

# Translation Memory

Translation Memory 保存 Provider 或 Agent 产生的自动译文。人工确认的最终措辞仍保存在项目内的
`overrides.json`，并始终优先于 Translation Memory。

## 默认：分片 JSON

默认配置会把自动译文写入 `i18n/translations/`。消息按稳定的 SHA-256 哈希前缀分片。新增或修改一条
译文只会影响对应分片和清单，适合在 PR 中审查。团队提交这些文件后，其他开发者和 CI 可以复用相同的
自动译文。旧版单文件 `i18n/translations.json` 会在下一次运行时自动迁移。

```ts
aiI18n({
  sourceLang: 'zh-CN',
  locales,
  translationMemory: {
    storage: 'json',
  },
});
```

分片文件与 `overrides.json` 应随源码提交。JSON 是默认存储，因此项目内不会生成 `storage.json`。
不要按行数手工移动消息；插件会稳定决定每条消息所在的分片。

`capacity` 只在需要限制历史译文时配置：

```ts
translationMemory: {
  storage: 'json',
  capacity: {
    maxMessages: 20_000,
    maxBytes: 10 * 1024 * 1024,
  },
}
```

它会淘汰当前源码不再引用的消息；活动消息始终保留，因此容量是软上限。容量计算不包含
`overrides.json`、`extracted/` 或 `locales/`。完整字段见
[`AiI18nTranslationMemoryCapacityOptions`](/ai-i18n/api/vite/interfaces/ai-i18n-translation-memory-capacity-options.md)。

## 可选：用户级全局 SQLite

希望同一台电脑上的多个项目共享自动译文时，可以选择 SQLite：

```ts
aiI18n({
  sourceLang: 'zh-CN',
  locales,
  translationMemory: {
    storage: 'sqlite',
  },
});
```

数据库位于当前用户的数据目录，不会写入项目，也不需要提交 Git。项目内会保留一个小型
`storage.json`，让 Vite 与 MCP 选择 SQLite。

当前项目已有自动译文时，SQLite 会继续使用该译文。当前项目尚无译文时，SQLite 才会查找跨项目候选。
原文、源语言、目标语言和 `comment` 必须完全一致。只有一个候选时，SQLite 会自动复用。存在多个不同
译法时，SQLite 会保持缺失，并交给 Provider 或人工审校。

默认数据库文件为 `translation-memory.sqlite`：macOS 位于
`~/Library/Application Support/ai-i18n/`，Linux 位于 `$XDG_DATA_HOME/ai-i18n/` 或
`~/.local/share/ai-i18n/`，Windows 位于 `%LOCALAPPDATA%\ai-i18n\`。

SQLite 是本机可丢弃缓存，不替代项目内的 `overrides.json`，也不是跨机器或团队同步服务。CI 或新电脑
没有该数据库时，可以由 Provider 重新生成自动译文。

## SQLite 未复用译文时如何排查

按以下顺序检查：

1. 检查项目内是否存在 `i18n/storage.json`。缺少该文件表示当前项目使用分片 JSON。
2. 检查 `AI_I18N_DATA_DIR` 是否已设置。已设置时，数据库位于该目录；否则使用当前平台的默认目录。
3. 运行一次完整 `vite build`，确认目标文案属于当前应用入口可达的模块。
4. 核对原文、源语言、目标语言和 `comment`。其中任意一项不同，都会产生不同的候选。
5. 确认是否存在多个不同译法。SQLite 不会从多个候选中猜测结果，因此会让该译文保持缺失。
6. 检查项目内的 `overrides.json`。人工译文拥有最高优先级，可能遮盖 SQLite 中的自动译文。

`provider.cache: 'fresh'` 会让当前 Vite 进程刷新自动译文，但不会解决候选冲突。请勿直接编辑 SQLite
数据库。需要重置本机缓存时，请先停止正在使用该数据库的 Vite 与 MCP 进程。删除数据库会清除本机的
自动译文缓存，后续可以由 Provider 重新生成；项目内的 `overrides.json` 不受影响。

## 模型或提示词变化后刷新一次

ai-i18n 不会根据 `model`、`baseURL`、温度或提示词自动失效缓存。自定义 `Translator` 可以封装任意
逻辑，插件无法可靠生成既安全又稳定的配置指纹，也不会把密钥或提示词写入项目文件。

需要用新配置重跑时，将 Provider 缓存策略临时设为 `fresh`：

```ts
aiI18n({
  sourceLang: 'zh-CN',
  locales,
  provider: {
    translator,
    cache: 'fresh',
  },
});
```

`fresh` 与 Dev/Build 无关。它只要求当前 Vite 进程向 Provider 刷新一次已有自动译文。历史译文仍可供
Runtime 使用；本进程新生成的结果会持久化并立即复用，普通 HMR 和重复模块访问不会持续调用模型。
重新启动时，如果仍保留 `fresh`，会再刷新一次；完成重译后通常改回默认的 `reuse`。

`provider.cache` 不属于 Translation Memory 存储配置，也不会传给 Translator。MCP 与 AI Agent 在
`storage.json` 缺失时读写分片 JSON，存在 SQLite 标记时读写全局数据库；在途 Agent 写入不会被旧
Provider 请求覆盖。`fresh` 也不会删除或覆盖人工 `overrides`。若只想重置少量自动译文，使用 MCP
的清除工具更合适。

## 切换存储

修改 `storage` 后，插件会迁移当前项目的 Translation Memory。切换到 SQLite 时创建
`storage.json`，切回 JSON 时删除该文件。切换前请停止其他正在写入该项目的 Vite 或 MCP 进程，
完成后检查生成文件和关键页面。

全局数据库目录可以通过 `AI_I18N_DATA_DIR` 覆盖，主要用于隔离 CI、容器或测试环境。不要把该目录
放进仓库。



---
url: https://bosens-china.github.io/ai-i18n/guide/advanced/ai-tools.md
---

# 使用 Agent 补译

Agent + MCP 适合希望在明确指令下补译、审校和验证翻译的团队。如果希望开发或构建期间自动调用模型，
请使用 [AI 翻译](/ai-i18n/guide/advanced/ai-translation.md)。

开始前，请先在目标 Vite 应用中完成 ai-i18n 接入，并运行一次完整 `vite build`。这样 Agent 才能读取
当前应用的文案清单。

## 安装 Skills

推荐在项目根目录安装 ai-i18n 提供的 Skills：

```sh
npx skills add bosens-China/ai-i18n --skill use-ai-i18n-mcp integrate-ai-i18n -y
```

安装后，你可以直接让 Agent 执行以下任务：

- “使用 `integrate-ai-i18n` 检查这个 Vite 应用的接入。”
- “使用 `use-ai-i18n-mcp` 补齐缺失的英文翻译，不要覆盖已有译文。”

Skills 会引导 Agent 选择正确的 Vite 应用，并区分自动译文与人工审校结果。

## 给 Agent 的文档入口

Rspress Build 会在文档站根目录生成
[`llms.txt`](https://bosens-china.github.io/ai-i18n/llms.txt) 和
[`llms-full.txt`](https://bosens-china.github.io/ai-i18n/llms-full.txt)：

- `llms.txt` 是带页面说明的精简索引。建议 Agent 先读它，再打开与当前框架或功能直接相关的
  Markdown 页面。
- `llms-full.txt` 包含完整文档正文，适合需要一次性导入整套资料的工具；日常编码任务不必默认
  加载，以免占用过多上下文。

Skills 只维护 Agent 的目标选择、默认决策、写入与授权边界、验证和错误恢复。安装、配置、API、
框架示例与排障方法以本文档站为准，因此 Agent 遇到具体产品用法时应从 `llms.txt` 定位页面，
而不是依赖 Skill 中复制的教程。

## 注册 MCP 服务器

ai-i18n 支持 Codex、Cursor、Claude Code 和 Antigravity。请在所使用的 AI 编码工具中注册
`@ai-i18n/mcp`。以下命令和配置以当前 alpha 版本为例。

### Codex

在本机终端运行以下命令即可注册：

```sh
codex mcp add ai-i18n -- npx -y @ai-i18n/mcp@alpha
```

也可以在 `~/.codex/config.toml` 或项目的 `.codex/config.toml` 中加入：

```toml
[mcp_servers.ai_i18n]
command = "npx"
args = ["-y", "@ai-i18n/mcp@alpha"]
```

也可以在 Codex 桌面端依次打开 **Settings → MCP servers → Add server → STDIO**，填写相同的
`command` 和 `args`。

### Cursor

在项目的 `.cursor/mcp.json` 或全局 `~/.cursor/mcp.json` 中加入：

```json
{
  "mcpServers": {
    "ai-i18n": {
      "command": "npx",
      "args": ["-y", "@ai-i18n/mcp@alpha"]
    }
  }
}
```

### Claude Code

```sh
claude mcp add --transport stdio --scope local ai-i18n -- npx -y @ai-i18n/mcp@alpha
```

### Antigravity

在项目的 `.agents/mcp_config.json` 中加入以下内容。若希望所有项目共用，可改为全局
`~/.gemini/config/mcp_config.json`：

```json
{
  "mcpServers": {
    "ai-i18n": {
      "command": "npx",
      "args": ["-y", "@ai-i18n/mcp@alpha"]
    }
  }
}
```

在 Antigravity IDE 中，也可以从 Agent 面板的 **MCP Servers → Manage MCP Servers → View raw config**
打开同一份配置。当前 ai-i18n 未收录在 Antigravity MCP Store，因此需要添加自定义服务器配置。

Cursor 和 Antigravity 对自定义本地 STDIO 服务器均使用配置文件。它们的 MCP Store 一键安装仅适用于
已收录的服务器；ai-i18n 收录前，请使用本页配置。

## 推荐提示词

完成配置后，将下面的提示发给 Agent：


给 Agent

批量补齐缺失翻译

复制后发送给 Agent。

复制 Prompt

使用 use-ai-i18n-mcp：
1. 确认目标 Vite 应用，并在需要时先运行一次完整 Build；
2. 按原文语义和项目已有术语补齐缺失的英文翻译；
3. 不要覆盖已有自动译文；
4. 列出需要人工确认的文案和建议措辞，得到确认后再写入人工审校结果；
5. 再次检查剩余缺失项并汇报。

## 使用边界

- Agent 补译默认保留已有译文。需要修改已确认的措辞时，请明确说明“审校”或“覆盖”。
- 人工审校结果优先于自动译文。Agent 应先展示建议措辞，得到确认后再写入。
- 在 monorepo 中，请说明目标应用名称或目录，避免 Agent 处理错误的 Vite 应用。
- Agent 只在指定应用内处理翻译，不会自动扩展到仓库中的其他应用。
- 同一条文案在多个文件中复用时，Agent 只需翻译一次，并会汇报实际影响范围。
- 大型项目会自动分批处理；完成后，Agent 会再次检查剩余缺失项。
- 大型清单默认不携带逐文件出现明细；只有排查文件或汇报影响范围时，Agent 才会额外请求。
- 短文案缺少语境时，Agent 可以按需取得每个出现文件及行列位置，再读取附近源码；这些位置不会
  改变同一句文案跨文件共享一份翻译的规则。
- 带动态值的文案会校验全部编号占位符；缺少、多出或改变编号时，整批写入不会生效，Agent 会按
  返回的差异修正后重试。
- 同一文案出现互相矛盾的译文时，Agent 会请求确认，不会自行猜测。
- Agent 工作期间不要并行手动修改同一份译文文件；完成后再进行人工审校。
- 普通补译和审校不会自动清理历史消息。只有你明确要求审查孤立消息时，Agent 才会在完整
  Build 后列出当前源码不再引用的 Translation Memory；删除前会展示结果并再次请求确认。
- 清理孤立的自动译文不会联动删除人工审校结果。需要删除孤立人工值时，应单独提出并审查。
- 生成文件和提交规则见[生成文件与 Git](/ai-i18n/guide/basic/directory.md)。

MCP 提供读取、补译和人工审校所需的工具。具体工具字段属于 Agent 接入契约，通常不需要由
应用开发者手动调用。



---
url: https://bosens-china.github.io/ai-i18n/guide/faq/common.md
---

# 通用常见问题

Vue 模板、响应式更新和 `tRef()` 问题见 [Vue 常见问题](/ai-i18n/guide/faq/vue.md)。React JSX、组件订阅
和 React Compiler 问题见 [React 常见问题](/ai-i18n/guide/faq/react.md)。

## Vite 7 或更低版本能否使用？

不能。ai-i18n 当前要求 Vite ≥ 8。使用更低版本时，请先升级 Vite，并确认当前 Node.js
版本满足 Vite 8 的运行要求。

## 为什么会安装 fs-native-extensions？

`@ai-i18n/vite` 通过 `@ai-i18n/core` 依赖 `fs-native-extensions`。Vite 与
`@ai-i18n/mcp` 可能同时修改分片 JSON Translation Memory 或 `overrides.json`，因此需要跨进程文件锁，
把“读取 → 修改 → 原子写入”整体串行化。否则，两个进程同时读写时，后完成的进程可能覆盖
另一个进程的修改。

原子写入只能避免文件写到一半时损坏，无法避免并发读改写造成的数据丢失。Node.js 的
`node:fs` 目前也没有跨平台的 `flock` 等价 API，因此 ai-i18n 使用
`fs-native-extensions` 提供操作系统级文件锁。该依赖只在 Vite 和 MCP 的 Node.js 进程中
运行，不会进入浏览器产物。

当前发布包没有提供 Linux musl 预编译产物。使用 `node:24-alpine` 等 Alpine 构建镜像时，
可能出现包含 `ADDON_NOT_FOUND` 或 `linux-x64-musl` 的错误。请把 Node.js 构建阶段改为
glibc 镜像，例如 `node:24-bookworm-slim`。最终用于托管静态文件的 Nginx 阶段仍可继续
使用 Alpine。

## 是否支持 SSR？

当前 Runtime 仅支持浏览器端。SSR 阶段会跳过翻译提取、模块注册和 Runtime 注入，并输出
警告；`defineI18nMessages()` 的编译期消除仍会执行。

如果项目需要服务端渲染译文、按请求选择 locale 或避免首屏 source fallback，当前版本
无法提供完整支持。

## 是否需要安装 unplugin-auto-import？

不需要。ai-i18n 的自动导入是插件自身能力，安装 `unplugin-auto-import` 不会自动启用它。
如果项目因为其他 API 使用了 `unplugin-auto-import`，两者可以同时存在，但不要重复配置
ai-i18n Runtime API。

需要省略显式 import 时，请设置 `aiI18n({ autoImport: true })`。完整边界见
[自动导入](/ai-i18n/guide/basic/auto-import.md)。

## 为什么自动导入没有生效？

按顺序检查：

1. 确认 `aiI18n({ autoImport: true })` 已显式开启。
2. 确认使用了当前模式支持的 API：三种模式都提供 `t`、语言 API 和 `subscribe`；Vue
   额外提供 `useI18n`、`tRef`、`i18nComputed` 与 `tComputed`，React 额外提供
   `useI18n`。
3. 修改 Vite 配置后重启开发服务器。
4. TypeScript 或 Vue template 报未定义时，按
   [TypeScript 与生成声明](/ai-i18n/guide/quality/typescript.md)确认生成文件。
5. ESLint 项目使用与框架匹配的 `vanilla-auto-import`、`vue-auto-import` 或
   `react-auto-import` preset。

局部变量、函数参数或显式 import 与自动导入 API 同名时，本地 binding 始终优先。Vue
template 可以直接使用未绑定的 `t()`；组件自身同名 binding 会遮挡自动导入。详见
[Vue 常见问题](/ai-i18n/guide/faq/vue.md)。

## 为什么 Dev 没有提取某个页面？

Vite Dev 只分析浏览器实际请求到的模块。懒路由尚未访问时，对应模块不会进入当前提取结果。
先访问目标页面，再检查 `extracted/*.json`。

需要确认生产入口的完整覆盖范围时，运行一次 `vite build`。Build 只分析从入口可达的模块，
不会扫描未被项目引用的文件。

## 为什么源码中的 `t()` 没有被提取，但调整 Vite 插件顺序后恢复了？

Vite 插件会按顺序转换模块。ai-i18n 已经运行在 `pre` 阶段，通常会早于 Vue、React 等普通
转换；但另一个同为 `pre` 的插件仍可能先替换宏或改写源码，使 ai-i18n 只能看到转换后的结果。

按以下顺序排查：

1. 运行一次完整 `vite build`，确认目标模块可从应用入口到达。Dev 未访问的懒路由不会参与处理。
2. 确认这段文案确实应由 ai-i18n 的 `t()` 翻译，而不是由另一个构建期宏自行处理。
3. 临时禁用可能改写源码的前置插件并重新 Build。提取恢复时，说明该插件在 ai-i18n 之前移除了
   调用。
4. 如果 `t()` 确实属于 ai-i18n，把 `aiI18n()` 放在同阶段的源码改写插件之前，再检查两者是否
   设置了更细的 hook 顺序。修改后重启 Dev 或重新 Build。

不要为了让 ai-i18n 提取而给其他插件拥有的宏字段添加 `t()`。例如权限插件本来就会翻译页面标题时，
应保持它要求的静态值：

```ts
definePagePermissions({
  title: '详情',
});
```

此时标题没有进入 ai-i18n 的提取结果是正常行为，不需要调整插件顺序，也不需要声明宏白名单。

## 为什么切换语言后仍然显示源文案？

缺失翻译或值为 `null` 时，Runtime 固定回退到 source。检查
当前 Translation Memory 或 `i18n/overrides.json` 中是否存在目标 locale 的有效译文，并让
运行中的 Vite Dev 自动同步，或重新执行一次 Vite Build。

可以通过 [AI 翻译](/ai-i18n/guide/advanced/ai-translation.md)配置 Provider，也可以通过
[接入 Agent](/ai-i18n/guide/advanced/ai-tools.md)补齐缺失翻译。协议文件职责见
[生成文件与 Git](/ai-i18n/guide/basic/directory.md)。

## 为什么按需加载语言包时切换失败？

配置 `loading` 后，未加载的目标语言会在 `setLang()` 时请求独立 chunk。加载失败时，
Promise 会 reject，并保留当前语言。Vue Composition 与 React 组件可使用 `useI18n()`
返回的 `isLangLoading` 和 `langLoadState.status === 'error'` 显示状态；纯 Vue Options
组件把 `i18nComputed()` 展开到 `computed` 后读取同名字段。需要业务级恢复动作时，捕获
Promise 并提供重试入口。

同时确认 `preload` 和 `prefetch` 只包含已配置的目标 locale，未包含 `sourceLang`，并且
同一 locale 没有同时出现在两个列表中。完整示例见
[语言分包与按需加载](/ai-i18n/guide/basic/locale-loading.md)。

## 生成文件是否需要提交？

需要。权威译文与生成声明随源码提交，可重建的提取结果和语言包不提交。完整文件清单、Build
时机与 Monorepo 归属统一见[生成文件与 Git](/ai-i18n/guide/basic/directory.md)；声明文件本身的作用见
[TypeScript 与生成声明](/ai-i18n/guide/quality/typescript.md)。

## 修改模型或提示词后，为什么没有重新翻译？

Translation Memory 默认复用历史结果。插件不能可靠识别自定义 Translator 内部的模型、温度、提示词或
`baseURL`，也不会把这些配置写入缓存指纹。需要刷新一次时，在 Provider 中配置
`cache: 'fresh'`。本次 Vite 进程会主动刷新已有自动译文，并继续复用本进程新生成的结果。该选项不影响
MCP 或 AI Agent。完成后改回默认 `reuse`。详见
[Translation Memory](/ai-i18n/guide/advanced/translation-memory.md)。

## 为什么 SQLite 没有复用另一个项目的译文？

SQLite 不会复用所有历史译文。当前项目尚无译文时，原文、源语言、目标语言和 `comment` 必须完全一致，
并且只能存在一个译文候选。多个候选可能代表不同语境，ai-i18n 会保持缺失，不会自动猜测。

请先确认项目内存在 `i18n/storage.json`，再按
[SQLite 未复用译文时如何排查](/ai-i18n/guide/advanced/translation-memory.md#sqlite-未复用译文时如何排查)逐项检查。



---
url: https://bosens-china.github.io/ai-i18n/guide/faq/vue.md
---

# Vue 常见问题

## 为什么模板里找不到 `t`？

未开启自动导入时，从虚拟模块显式导入：

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

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

开启 `autoImport: true` 后，可以只保留 template：

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

插件生成的声明会让 Vue language-tools（Volar）与 `vue-tsc` 识别这个裸 `t`，
无需为了 IDE 添加 import。`<script setup>`、普通 `<script>` 和纯 Options 也可以直接使用。
如果仍提示找不到 `t`，按
[TypeScript 与生成声明](/ai-i18n/guide/quality/typescript.md)检查 Vue 的两份声明文件。

自动导入只处理未绑定的 `t`。模板局部变量和组件自身同名 prop、data、computed、method、
inject 或 setup 返回值会遮挡它。本地 binding 始终优先。

关闭自动导入时，已有普通 `<script>` 或 Options API 组件仍使用同一个顶层 `t`：

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

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

<template>
  <button :title="label">{{ t('保存') }}</button>
</template>
```

Options 的普通 `<script>` import 只存在于模块作用域，不会像 `<script setup>` 顶层
binding 一样自然暴露给 template，所以显式导入模式需要 `methods: { t }`。开启自动导入后，
应同时删除 `t` import 和这个 method bridge。脚本调用始终直接写 `t()`；`this.t`、
`this.$t`、mixin 与 `globalProperties` 不属于静态提取写法。

## 为什么普通模板文本没有被提取？

ai-i18n 不猜测普通 UI 文本。把需要翻译的文本放入已绑定的 `t()`：

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

支持的静态表达式、文案树与限制见 [Vue 文案写法](/ai-i18n/guide/basic/static-analysis/vue.md)。

## 为什么切换语言后组件没有刷新？

Vue 模式从 `virtual:ai-i18n` 导出的顶层 `t` 会读取 adapter revision。在 template、
render 或 computed 中调用时，Vue 会建立响应式依赖并在语言切换后刷新。

`useI18n()` 返回的 `t` 就是这个顶层函数。Vue adapter 统一维护 revision，不需要每个组件
调用 Composable 来为翻译函数单独订阅。未开启自动导入时显式 import `t`；开启后直接调用
裸 `t()`。需要 `currentLang`、加载状态或 `setLang` 时，再从 `useI18n()` 取得对应的 Ref
和 action。

如果在 setup 中保存了 `const label = t('保存')`，得到的也只是当前快照。直接在模板中调用
`t('保存')`，或使用 Vue-only `const label = tRef('保存')`。`tRef()` 返回只读
ComputedRef，应在 setup 或 composable 中创建一次，不要在模板或 render 函数中调用。

## 为什么脚本中读取 `currentLang` 得到的是 Ref？

Vue 适配器返回只读响应式值。模板会自动解包，`<script setup>` 中请读取
`currentLang.value`。`langs`、`langLoadState`、`isLangLoading` 与 `langLoadError` 采用相同
规则。纯 Options 组件把 [`i18nComputed()`](/ai-i18n/api/runtime/vue/i18n-computed.md) 展开到
`computed` 后，读取的是已经解包的值：

```ts
export default defineComponent({
  computed: {
    ...i18nComputed(),
  },
  watch: {
    currentLang(next: string, previous: string) {
      console.log(previous, '->', next);
    },
  },
});
```

Options API 的组件实例与 watch 参数类型问题见
[TypeScript 与生成声明](/ai-i18n/guide/quality/typescript.md)。

## Pinia 或普通 TS 文件能否直接使用语言 API？

可以。Vue 模式的 `autoImport: true` 同时提供 `setLang()`、`getLang()`、`getLangs()`、
`getLangLoadState()` 与 `subscribe()`。Pinia action、路由守卫和普通工具函数可以直接调用。

`getLang()` 与 `getLangLoadState()` 返回调用时快照，不是 Ref。Store 要长期暴露响应式语言
状态时，使用 `useI18n()` 返回的只读 Ref，或通过 `subscribe()` 同步并在销毁时取消订阅。

## `tRef()` 是否来自 `useI18n()`？

不是。`tRef` 是 Vue 模式下由 `virtual:ai-i18n` 独立导出的 API：

```vue
<script setup lang="ts">
import { tRef } from 'virtual:ai-i18n';

const label = tRef('保存');
</script>

<template>{{ label }}</template>
```

需要完整签名和文案树示例时，查看 [`tRef()` API](/ai-i18n/api/runtime/vue/t-ref.md)。

## 纯 Options API 如何预声明响应式文案？

使用 [`tComputed()`](/ai-i18n/api/runtime/vue/t-computed.md)，并把返回的 getter 放入 Options
`computed`：

```ts
export default defineComponent({
  computed: {
    saveLabel: tComputed('保存'),
    labels: tComputed({ save: '保存', cancel: '取消' }),
  },
});
```

不要把 `tComputed()` 放入 `data()`，也不要在 template 或 render 中调用。依赖
`this` 的动态插值应写成普通 computed，并在 getter 中调用 `t()`。



---
url: https://bosens-china.github.io/ai-i18n/guide/faq/react.md
---

# React 常见问题

## 为什么普通 JSX 文本没有被提取？

ai-i18n 不猜测普通 UI 文本。把需要翻译的文本放入 `useI18n()` 返回的 `t()`：

```tsx
import { useI18n } from 'virtual:ai-i18n';

function SaveButton() {
  const { t } = useI18n();
  return <button>{t('保存')}</button>;
}
```

支持的静态表达式、文案树与限制见 [React 文案写法](/ai-i18n/guide/basic/static-analysis/react.md)。

## 为什么切换语言后组件没有刷新？

组件渲染必须调用 `useI18n()` 返回的 `t`。从 `virtual:ai-i18n` 单独导入的顶层 `t` 只读取
当前语言，不会让组件订阅后续更新。

也不要把 `t('保存')` 的结果放入模块常量或长期 state。保留 source 文案，在每次渲染时调用
Hook 返回的 `t()`。

## 非组件 TS 文件如何读取或切换语言？

普通模块、store action、路由和事件处理器不能调用 React Hook，应使用顶层 Runtime API。
开启 `autoImport: true` 后，可以直接调用 `setLang()`、`getLang()`、`getLangs()`、
`getLangLoadState()` 与 `subscribe()`。

其中 `getLang()` 与 `getLangLoadState()` 返回调用时快照。组件需要展示这些状态时仍应使用
`useI18n()`，否则语言变化不会触发重新渲染。

## React Compiler 能否替代 `useI18n()`？

不能。React Compiler 可以缓存渲染计算，但不会为 Runtime 顶层 `t` 自动建立外部状态订阅。
`useI18n()` 内部使用 `useSyncExternalStore`，Runtime 更新时还会刷新 `t` 的函数引用，因此
无论是否启用 React Compiler，组件渲染都应使用 Hook 返回的 `t`。

## 普通工具模块不能调用 Hook，应该怎么翻译？

普通 `.js` 或 `.ts` 工具模块可以导入 Runtime 顶层 `t`，但应在实际调用时翻译：

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

export const getRetryMessage = () => t('请重试');
```

不要导出 `const retryMessage = t('请重试')`，它只保存模块初始化时的译文快照。组件渲染仍
使用 `useI18n()`。

## 本地 link 后为什么出现 Invalid Hook Call？

先确认应用只解析到一份 `react` 和 `react-dom`。本地工作区或 link 场景可在 Vite 中添加：

```ts
export default defineConfig({
  resolve: {
    dedupe: ['react', 'react-dom'],
  },
});
```

正常安装通常由 peer dependency 复用应用自己的 React，不需要额外配置。



---
url: https://bosens-china.github.io/ai-i18n/api/index.md
---

# API 总览

需要完成安装、配置和业务接入时，从[快速上手](/ai-i18n/guide/getting-started/vue.md)与
[接入与使用](/ai-i18n/guide/basic/static-analysis/common.md)开始。本节只负责记录公开 API 的准确签名、
配置字段、默认值与行为边界，不重复教程流程。

API 参考按导入入口组织。选择入口后，再按函数、接口、类型别名或编译宏查找具体符号。

| 入口                     | 用途                               |
| ---------------------- | -------------------------------- |
| `@ai-i18n/vite`        | 注册 Vite 插件，配置提取、翻译和自定义 Provider。 |
| `@ai-i18n/vite/vitest` | 在 Vitest 中提供内存 Runtime 与编译宏转换。   |
| `virtual:ai-i18n`      | 在浏览器业务代码中翻译文案和切换语言。              |
| `@ai-i18n/openai`      | 创建 OpenAI-compatible Translator。 |

## 查找入口

- 配置插件：[`aiI18n()`](/ai-i18n/api/vite/functions/ai-i18n.md)
- 查询全部插件选项：[`AiI18nOptions`](/ai-i18n/api/vite/interfaces/ai-i18n-options.md)
- 翻译文案：[`t()`](/ai-i18n/api/runtime/functions/t.md)
- 在 Vue setup 中创建响应式翻译值：[`tRef()`](/ai-i18n/api/runtime/vue/t-ref.md)
- 读取语言资源加载状态：[`getLangLoadState()`](/ai-i18n/api/runtime/functions/get-lang-load-state.md)
- 在 Vue 中读取响应式语言状态：[`useI18n()`](/ai-i18n/api/runtime/vue/use-i18n.md)
- 在 React 中订阅语言变化：[`useI18n()`](/ai-i18n/api/runtime/react/use-i18n.md)
- 配置 Vitest：[`aiI18nVitest()`](/ai-i18n/api/vitest/functions/ai-i18n-vitest.md)
- 连接模型：[`openAI()`](/ai-i18n/api/openai/functions/open-ai.md)
- 实现自定义翻译器：[`Translator`](/ai-i18n/api/vite/type-aliases/translator.md)

## 本节职责

本节记录应用接入所依赖的公开契约。Analyzer、文件 Schema、Translation Memory 事务和框架
适配器等低层基础设施不作为普通应用的稳定接入入口。除非文档明确列出，否则不要依赖包中
的其他导出。



---
url: https://bosens-china.github.io/ai-i18n/api/vite/functions/ai-i18n.md
---

# aiI18n()

从 `@ai-i18n/vite` 导入：

```ts
import { aiI18n } from '@ai-i18n/vite';
```

## 签名

```ts
function aiI18n(options: AiI18nOptions): Plugin;
```

`aiI18n()` 返回一个 Vite 插件。每个 Vite build 只应注册一次。

## 示例

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

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

配置完成后，业务代码从 `virtual:ai-i18n` 导入 Runtime API：

```ts
import { setLang, t } from 'virtual:ai-i18n';
```

## 参数

| 参数        | 类型                                                                 | 说明           |
| --------- | ------------------------------------------------------------------ | ------------ |
| `options` | [`AiI18nOptions`](/ai-i18n/api/vite/interfaces/ai-i18n-options.md) | Vite 插件完整配置。 |

## 返回值

返回 Vite 的 `Plugin` 对象。插件负责静态提取、协议文件同步、可选 Provider 调度、虚拟
Runtime 和声明文件生成。

## 相关内容

- [Vue 快速上手](/ai-i18n/guide/getting-started/vue.md)
- [React 快速上手](/ai-i18n/guide/getting-started/react.md)
- [Vanilla 快速上手](/ai-i18n/guide/getting-started/vanilla.md)
- [通用文案写法](/ai-i18n/guide/basic/static-analysis/common.md)
- [生成文件与 Git](/ai-i18n/guide/basic/directory.md)



---
url: https://bosens-china.github.io/ai-i18n/api/vite/interfaces/ai-i18n-options.md
---

# AiI18nOptions

从 `@ai-i18n/vite` 导入：

```ts
import type { AiI18nOptions } from '@ai-i18n/vite';
```

## 定义

```ts
interface AiI18nOptions {
  framework?: AiI18nFramework;
  autoImport?: boolean;
  dts?: string | false;
  sourceLang: string;
  defaultLang?: string;
  locales: readonly LangOption[];
  persist?: boolean | AiI18nPersistOptions;
  loading?: AiI18nLocaleLoadingOptions;
  translationMemory?: AiI18nTranslationMemoryOptions;
  provider?: AiI18nProviderOptions;
  directory?: string;
  cleanup?: AiI18nCleanupOptions;
  html?: boolean | HtmlExtractorOptions;
}
```

## 字段

| 字段                  | 类型                                                                                                     | 必填 | 默认值                  | 作用                         |
| ------------------- | ------------------------------------------------------------------------------------------------------ | -- | -------------------- | -------------------------- |
| `sourceLang`        | `string`                                                                                               | 是  | 无                    | 源码文案所属语言。                  |
| `locales`           | [`readonly LangOption[]`](/ai-i18n/api/vite/interfaces/lang-option.md)                                 | 是  | 无                    | 项目支持的语言列表。                 |
| `defaultLang`       | `string`                                                                                               | 否  | `sourceLang`         | 没有有效持久化值时使用的初始语言。          |
| `persist`           | `boolean` 或 [`AiI18nPersistOptions`](/ai-i18n/api/vite/interfaces/ai-i18n-persist-options.md)          | 否  | `false`              | 使用 localStorage 保存语言偏好。    |
| `loading`           | [`AiI18nLocaleLoadingOptions`](/ai-i18n/api/vite/interfaces/ai-i18n-locale-loading-options.md)         | 否  | 全语言注册                | 按 locale 拆分语言资产。           |
| `framework`         | [`AiI18nFramework`](/ai-i18n/api/vite/type-aliases/ai-i18n-framework.md)                               | 否  | 自动检测                 | 指定 Vanilla、Vue 或 React 模式。 |
| `autoImport`        | `boolean`                                                                                              | 否  | `false`              | 自动注入当前框架模式的 Runtime API。   |
| `dts`               | `string \| false`                                                                                      | 否  | `'src/ai-i18n.d.ts'` | 设置声明文件路径，或关闭生成。            |
| `directory`         | `string`                                                                                               | 否  | `'i18n'`             | 设置协议目录；相对路径基于 Vite `root`。 |
| `provider`          | [`AiI18nProviderOptions`](/ai-i18n/api/vite/type-aliases/ai-i18n-provider-options.md)                  | 否  | 不调用模型                | 配置自动翻译函数、缓存与调度策略。          |
| `html`              | [`boolean \| HtmlExtractorOptions`](/ai-i18n/api/vite/interfaces/html-extractor-options.md)            | 否  | `false`              | 开启 `index.html` 文本和属性提取。   |
| `translationMemory` | [`AiI18nTranslationMemoryOptions`](/ai-i18n/api/vite/interfaces/ai-i18n-translation-memory-options.md) | 否  | 分片 JSON              | 选择存储方式，并按需限制历史译文容量。        |
| `cleanup`           | [`AiI18nCleanupOptions`](/ai-i18n/api/vite/interfaces/ai-i18n-cleanup-options.md)                      | 否  | 保留默认清理策略             | 控制失效提取文件和孤立消息的清理。          |

## 语言约束

`locales` 至少包含一项，且每一项的 `value` 必须唯一。`sourceLang` 与 `defaultLang` 必须匹配
某个 `value`。

目标语言缺译或值为 `null` 时，Runtime 返回 source 文案。插件不会为 `sourceLang` 生成重复的
目标语言文件。

初始语言按以下顺序选择：

1. localStorage 中有效的持久化值；
2. `defaultLang`；
3. 省略 `defaultLang` 时使用 `sourceLang`。

## 框架与自动导入

省略 `framework` 时，插件读取 Vite 最终插件列表：

| 检测结果                           | 模式        |
| ------------------------------ | --------- |
| 存在 `vite:vue` 或 `vite:vue-jsx` | `vue`     |
| 存在 `vite:react*`               | `react`   |
| 都不存在                           | `vanilla` |

同一个 build 同时出现 Vue 与 React 插件时会报错。显式设置 `framework` 不会绕过这项检查。
显式值只能是 `'vanilla'`、`'vue'` 或 `'react'`；JavaScript 配置中的其他值也会在启动时被拒绝。

`autoImport: true` 注入的 API 取决于最终模式。三种模式都有 `t`、`setLang`、`getLang`、
`getLangs`、`getLangLoadState` 与 `subscribe`；Vue 额外注入 `useI18n`、`tRef`、
`i18nComputed`、`tComputed`，React 额外注入 `useI18n`。

完整接入方法见[自动导入](/ai-i18n/guide/basic/auto-import.md)。

## 路径

`directory` 与 `dts` 的相对路径都基于 Vite `root` 解析；传入绝对路径时直接使用该路径。

## 相关内容

- [`aiI18n()`](/ai-i18n/api/vite/functions/ai-i18n.md)
- [语言分包与按需加载](/ai-i18n/guide/basic/locale-loading.md)
- [生成文件与 Git](/ai-i18n/guide/basic/directory.md)
- [TypeScript 与生成声明](/ai-i18n/guide/quality/typescript.md)
- [Translation Memory](/ai-i18n/guide/advanced/translation-memory.md)
- [ESLint](/ai-i18n/guide/quality/eslint.md)



---
url: https://bosens-china.github.io/ai-i18n/api/vite/interfaces/ai-i18n-persist-options.md
---

# AiI18nPersistOptions

从 `@ai-i18n/vite` 导入：

```ts
import type { AiI18nPersistOptions } from '@ai-i18n/vite';
```

## 定义

```ts
interface AiI18nPersistOptions {
  key: string;
}
```

## 字段

| 字段    | 类型       | 必填 | 作用                        |
| ----- | -------- | -- | ------------------------- |
| `key` | `string` | 是  | 保存当前语言的 localStorage key。 |

`key` 去除首尾空白后不能为空。

## 用法

[`AiI18nOptions.persist`](/ai-i18n/api/vite/interfaces/ai-i18n-options.md) 支持三种写法：

| 写法                        | 行为                 |
| ------------------------- | ------------------ |
| `false` 或省略               | 不读写 localStorage。  |
| `true`                    | 使用 `ai-i18n:lang`。 |
| `{ key: 'app-language' }` | 使用指定 key。          |

存储不可用或保存值不在 `locales` 中时，Runtime 会忽略该值。



---
url: https://bosens-china.github.io/ai-i18n/api/vite/interfaces/ai-i18n-locale-loading-options.md
---

# AiI18nLocaleLoadingOptions

从 `@ai-i18n/vite` 导入：

```ts
import type { AiI18nLocaleLoadingOptions } from '@ai-i18n/vite';
```

## 定义

```ts
interface AiI18nLocaleLoadingOptions {
  preload?: readonly string[];
  prefetch?: readonly string[];
}
```

## 字段

| 字段         | 类型                  | 默认值  | 作用                           |
| ---------- | ------------------- | ---- | ---------------------------- |
| `preload`  | `readonly string[]` | `[]` | 通过 `modulepreload` 尽早准备语言模块。 |
| `prefetch` | `readonly string[]` | `[]` | 通过 `prefetch` 提示浏览器低优先级缓存。   |

## 行为

设置 `loading` 后，每个目标 locale 会生成独立 Vite chunk。省略 `loading` 时，插件继续使用
全语言注册模式；`loading: {}` 则会启用分包，并在首次 `setLang()` 时加载目标语言。

列表必须满足以下约束：

- 只能引用 `locales` 中的目标 locale；
- 不能包含 `sourceLang`；
- 同一 locale 不能同时出现在两个列表中；
- 单个列表中的重复值会自动去重。

非 source 的 `defaultLang` 会自动加入 `preload`，因此不能再把它列入 `prefetch`；该组合会在启动时
报错。相同 locale 的并发调用复用底层加载请求；不同 locale 的并发切换以最后一次 `setLang()` 调用为准。

## 示例

```ts
aiI18n({
  sourceLang: 'zh-CN',
  defaultLang: 'en-US',
  locales,
  loading: {
    preload: ['en-US'],
    prefetch: ['ja-JP'],
  },
});
```

完整使用流程见[语言分包与按需加载](/ai-i18n/guide/basic/locale-loading.md)。



---
url: https://bosens-china.github.io/ai-i18n/api/vite/interfaces/ai-i18n-translation-memory-capacity-options.md
---

# AiI18nTranslationMemoryCapacityOptions

从 `@ai-i18n/vite` 导入：

```ts
import type { AiI18nTranslationMemoryCapacityOptions } from '@ai-i18n/vite';
```

## 定义

```ts
interface AiI18nTranslationMemoryCapacityOptions {
  maxMessages?: number;
  maxBytes?: number;
}
```

## 字段

| 字段            | 类型       | 默认值 | 作用                            |
| ------------- | -------- | --- | ----------------------------- |
| `maxMessages` | `number` | 不限制 | 最多保留的 Translation Memory 消息数。 |
| `maxBytes`    | `number` | 不限制 | Memory 快照稳定序列化后的 UTF-8 字节软上限。 |

两个字段都必须是正整数。两项同时存在时，Memory 需要同时满足两个限制。容量统计包含当前项目的
Translation Memory 元数据与消息，不包含 `overrides`、`extracted` 或 `locales`。JSON 与 SQLite
使用相同的逻辑快照计算方式。

插件只淘汰当前源码不再引用的消息。活动消息始终保留；活动消息自身超限时，插件输出 warning，因此
这两个字段是保护数据安全的软上限。`cleanup.orphanMessages: true` 会先删除全部非活跃消息。

## 用法

```ts
aiI18n({
  sourceLang: 'zh-CN',
  locales,
  translationMemory: {
    storage: 'json',
    capacity: {
      maxMessages: 20_000,
      maxBytes: 10 * 1024 * 1024,
    },
  },
});
```



---
url: https://bosens-china.github.io/ai-i18n/api/vite/interfaces/ai-i18n-cleanup-options.md
---

# AiI18nCleanupOptions

从 `@ai-i18n/vite` 导入：

```ts
import type { AiI18nCleanupOptions } from '@ai-i18n/vite';
```

## 定义

```ts
interface AiI18nCleanupOptions {
  missingSourceFiles?: boolean;
  orphanMessages?: boolean;
}
```

## 字段

| 字段                   | 默认值     | 作用                                |
| -------------------- | ------- | --------------------------------- |
| `missingSourceFiles` | `true`  | 删除源文件不存在时对应的 `extracted` 文件。      |
| `orphanMessages`     | `false` | 删除当前源码不再引用的历史 Translation Memory。 |

`orphanMessages: true` 会先删除当前项目的全部非活跃消息，再执行容量淘汰。它不会删除
`overrides.json`。SQLite 模式只影响当前项目的数据，不会删除其他项目的共享候选。

首次启用或修改清理策略后，运行一次完整 Build，确认当前入口可达模块已完成提取。



---
url: https://bosens-china.github.io/ai-i18n/api/vite/interfaces/ai-i18n-translation-memory-options.md
---

# AiI18nTranslationMemoryOptions

从 `@ai-i18n/vite` 导入：

```ts
import type { AiI18nTranslationMemoryOptions } from '@ai-i18n/vite';
```

## 定义

```ts
interface AiI18nTranslationMemoryOptions {
  storage?: 'json' | 'sqlite';
  capacity?: AiI18nTranslationMemoryCapacityOptions;
}
```

## 字段

| 字段         | 类型                                                                                                                      | 默认值      | 作用                              |
| ---------- | ----------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------- |
| `storage`  | `'json' \| 'sqlite'`                                                                                                    | `'json'` | 使用项目内可提交的分片 JSON，或用户级全局 SQLite。 |
| `capacity` | [`AiI18nTranslationMemoryCapacityOptions`](/ai-i18n/api/vite/interfaces/ai-i18n-translation-memory-capacity-options.md) | 不限制      | 限制当前项目保留的历史译文容量。                |

`storage: 'sqlite'` 使用用户目录中的同一个本地数据库，在不同项目间复用唯一译文候选。数据库不在
项目目录内，也不应提交 Git；`overrides.json` 仍保留在项目内并拥有最高优先级。

Provider 的进程级刷新通过 `provider.cache` 配置，不属于存储选项，也不影响 MCP。完整行为和选型建议见
[Translation Memory](/ai-i18n/guide/advanced/translation-memory.md)。



---
url: https://bosens-china.github.io/ai-i18n/api/vite/interfaces/html-extractor-options.md
---

# HtmlExtractorOptions

从 `@ai-i18n/vite` 导入：

```ts
import type { HtmlExtractorOptions } from '@ai-i18n/vite';
```

## 定义

```ts
interface HtmlExtractorOptions {
  attributes?: readonly string[];
}
```

## 字段

| 字段           | 类型                  | 默认值                                      | 作用           |
| ------------ | ------------------- | ---------------------------------------- | ------------ |
| `attributes` | `readonly string[]` | `alt`、`aria-label`、`placeholder`、`title` | 替换默认属性提取白名单。 |

属性名必须由小写字母开头，后续只能包含小写字母、数字和连词线。重复属性会自动去重。

## 用法

| `AiI18nOptions.html` 写法 | 行为                       |
| ----------------------- | ------------------------ |
| `false` 或省略             | 不处理 HTML。                |
| `true`                  | 提取完整的静态 `t()` 文本节点与默认属性。 |
| `{ attributes }`        | 提取完整的静态 `t()`，并替换属性白名单。  |

普通 HTML 文本、混合文本、内联脚本和非白名单属性不会自动翻译。HTML 提取与 `framework` 模式
相互独立。完整写法见[通用文案写法](/ai-i18n/guide/basic/static-analysis/common.md#html)。



---
url: https://bosens-china.github.io/ai-i18n/api/vite/interfaces/lang-option.md
---

# LangOption

从 `@ai-i18n/vite` 导入：

```ts
import type { LangOption } from '@ai-i18n/vite';
```

## 定义

```ts
interface LangOption {
  value: string;
  label: string;
}
```

## 字段

| 字段      | 类型       | 必填 | 作用                            |
| ------- | -------- | -- | ----------------------------- |
| `value` | `string` | 是  | 语言标识，用于 `setLang()` 和目标语言文件名。 |
| `label` | `string` | 是  | 面向用户的语言名称，由 `getLangs()` 返回。  |

`AiI18nOptions.locales` 至少包含一项，且所有 `value` 必须唯一。

```ts
const locales: readonly LangOption[] = [
  { value: 'zh-CN', label: '中文' },
  { value: 'en-US', label: 'English' },
];
```



---
url: https://bosens-china.github.io/ai-i18n/api/vite/interfaces/translation-options.md
---

# TranslationOptions

该类型从 `@ai-i18n/vite` 导出，并用于 `virtual:ai-i18n` 的 `t()` 签名：

```ts
import type { TranslationOptions } from '@ai-i18n/vite';
```

## 定义

```ts
interface TranslationOptions {
  comment?: string;
}
```

## 字段

| 字段        | 类型       | 必填 | 作用             |
| --------- | -------- | -- | -------------- |
| `comment` | `string` | 否  | 向翻译器说明文案的业务语境。 |

`comment` 必须能在构建期确定。插件会去除首尾空白；非空 `comment` 会参与消息身份与 Translation
Memory。相同原文使用不同的 `comment` 时属于不同翻译单元，不会共享译文。

```ts
t('保存', { comment: '按钮' });
t('保存', { comment: '文件状态' });
```

模型只翻译 source，comment 只用于理解语境，不会进入最终译文。



---
url: https://bosens-china.github.io/ai-i18n/api/vite/interfaces/translation-message.md
---

# TranslationMessage

从 `@ai-i18n/vite` 导入：

```ts
import type { TranslationMessage } from '@ai-i18n/vite';
```

## 定义

```ts
interface TranslationMessage {
  source: string;
  comment?: string;
}
```

## 字段

| 字段        | 类型       | 必填 | 作用              |
| --------- | -------- | -- | --------------- |
| `source`  | `string` | 是  | 需要翻译的源文案。       |
| `comment` | `string` | 否  | 用于理解业务语境，不进入译文。 |

Vite 不会把 message ID、文件路径或源码位置交给 Translator。



---
url: https://bosens-china.github.io/ai-i18n/api/vite/interfaces/translation-batch.md
---

# TranslationBatch

从 `@ai-i18n/vite` 导入：

```ts
import type { TranslationBatch } from '@ai-i18n/vite';
```

## 定义

```ts
interface TranslationBatch {
  batchId?: string;
  logging?: TranslationLogging;
  locales: readonly string[];
  messages: readonly TranslationMessage[];
}
```

## 字段

| 字段         | 类型                                                                                     | 必填 | 作用                    |
| ---------- | -------------------------------------------------------------------------------------- | -- | --------------------- |
| `batchId`  | `string`                                                                               | 否  | 本批诊断 ID；由 Vite 调度器生成。 |
| `logging`  | [`TranslationLogging`](/ai-i18n/api/vite/type-aliases/translation-logging.md)          | 否  | 关闭日志，或给出已解析日志目录。      |
| `locales`  | `readonly string[]`                                                                    | 是  | 本批所有消息共同缺失的语言。        |
| `messages` | [`readonly TranslationMessage[]`](/ai-i18n/api/vite/interfaces/translation-message.md) | 是  | 按固定下标排列的消息。           |

Vite 按缺失 locale 集合分组，再根据 `AiI18nProviderOptions.batchLength` 切分批次。
`batchId` 只用于把调度、模型日志、状态应用和持久化事件关联起来，不发送给模型，也不参与
message ID、缓存键或 Translation Memory 文件格式。直接调用 Translator 时，Translator 可以为缺失的
`batchId` 生成本地诊断 ID。

Vite 根据 `provider.logging` 传入 `logging`。启用时，字符串是基于 Vite root 解析后的绝对目录；
关闭时为 `false`。自定义 Translator 可以忽略该可选字段；官方 OpenAI Provider 在值为 `false` 时
仍执行翻译，但不创建或追加日志。实现 `reportBatchEvent` 的 Translator 仍会收到生命周期事件。



---
url: https://bosens-china.github.io/ai-i18n/api/vite/interfaces/translation-batch-event.md
---

# TranslationBatchEvent

从 `@ai-i18n/vite` 导入：

```ts
import type { TranslationBatchEvent } from '@ai-i18n/vite';
```

## 定义

```ts
type TranslationBatchEvent =
  | {
      batchId: string;
      logging: false | string;
      stage: 'scheduled';
      locales: readonly string[];
      messageCount: number;
    }
  | {
      batchId: string;
      logging: false | string;
      stage: 'state-applied';
      resultCount: number;
      affectedModules: number;
    }
  | { batchId: string; logging: false | string; stage: 'persisted' }
  | {
      batchId: string;
      logging: false | string;
      stage: 'failed';
      locales: readonly string[];
      messageCount: number;
      reason: string;
    };
```

`logging` 与对应 [`TranslationBatch`](/ai-i18n/api/vite/interfaces/translation-batch.md) 一致。启用时是基于
Vite root 解析后的绝对日志目录；关闭时为 `false`。实现了 `reportBatchEvent` 的 Translator 始终接收
事件；日志关闭只表示不应写入日志文件。该字段不进入持久化协议。

## 阶段

| `stage`         | 必有字段                              | 含义                                   |
| --------------- | --------------------------------- | ------------------------------------ |
| `scheduled`     | `locales`、`messageCount`          | Vite 已形成实际 Translator 批次。            |
| `state-applied` | `resultCount`、`affectedModules`   | Provider 结果已通过校验并应用到当前项目状态。          |
| `persisted`     | 无                                 | 包含该批结果的文件和 Translation Memory 已写入成功。 |
| `failed`        | `locales`、`messageCount`、`reason` | Translator、结果校验或后续批次处理失败。            |

事件接收器只用于观察，不能依赖它改变翻译流程。



---
url: https://bosens-china.github.io/ai-i18n/api/vite/type-aliases/ai-i18n-provider-options.md
---

# AiI18nProviderOptions

从 `@ai-i18n/vite` 导入：

```ts
import type { AiI18nProviderOptions } from '@ai-i18n/vite';
```

## 定义

```ts
type AiI18nProviderOptions = {
  translator: Translator;
  cache?: 'reuse' | 'fresh';
  debounceMs?: number;
  batchLength?: number;
  maxConcurrency?: number;
  strict?: boolean;
  logging?: boolean | string;
};
```

## 字段

| 字段               | 类型                                                           | 必填 | 默认值       | 作用                             |
| ---------------- | ------------------------------------------------------------ | -- | --------- | ------------------------------ |
| `translator`     | [`Translator`](/ai-i18n/api/vite/type-aliases/translator.md) | 是  | 无         | 执行自动翻译。                        |
| `cache`          | `'reuse' \| 'fresh'`                                         | 否  | `'reuse'` | 复用历史结果，或在本次进程中刷新一次。            |
| `debounceMs`     | `number`                                                     | 否  | `100`     | Dev 中合并连续请求的等待时间，单位为毫秒。        |
| `batchLength`    | `number`                                                     | 否  | `12_000`  | 单批序列化请求的字符长度上限，不是 token 数。     |
| `maxConcurrency` | `number`                                                     | 否  | `5`       | 同时执行的翻译批次数。                    |
| `strict`         | `boolean`                                                    | 否  | `false`   | 在 flush 时抛出翻译失败或仍有 `null` 的错误。 |
| `logging`        | `boolean \| string`                                          | 否  | `false`   | 关闭日志，或启用并选择日志目录。               |

`debounceMs` 必须大于或等于 `0`。`batchLength` 和 `maxConcurrency` 必须是正整数。

Vite 按消息的“缺失 locale 集合”分组，再按 `batchLength` 切分。一个批次失败时，其他成功
批次仍会写入。Dev 中的模型调用不阻塞首次模块响应；Build 会在结束前等待必要批次。

日志默认关闭。`logging: true` 使用 Vite root 下的 `logs/`；字符串指定目录，相对路径基于 Vite
root，绝对路径保持不变。空字符串无效。开启后，Vite 会把解析后的目录传给 Translator 和批次
生命周期事件。官方 OpenAI Provider 会据此记录 REQUEST、RESPONSE、VALIDATION 等日志；省略或设为
`false` 时不创建或追加日志，但翻译、状态应用和持久化继续执行。自定义 Translator 可以选择支持该
诊断字段。完整说明见
[LLM 日志与排障](/ai-i18n/guide/advanced/llm-logs.md)。

`cache: 'fresh'` 只影响当前 Vite 进程发起的 Provider 调用。已有译文仍可供 Runtime 使用；本进程
生成的新结果会立即缓存，普通 HMR 不会重复请求。该选项不传给 Translator，也不影响 MCP 或 AI Agent
读写 Translation Memory。它与 `translationMemory.capacity` 无关：前者控制一次 Provider 刷新，后者
控制历史 Translation Memory 的容量。

## 示例

```ts
aiI18n({
  sourceLang: 'zh-CN',
  locales,
  provider: {
    translator,
    batchLength: 12_000,
    maxConcurrency: 5,
    strict: true,
    logging: 'diagnostics/llm',
  },
});
```

Provider 的完整接入流程见 [AI 翻译](/ai-i18n/guide/advanced/ai-translation.md)。



---
url: https://bosens-china.github.io/ai-i18n/api/vite/type-aliases/ai-i18n-framework.md
---

# AiI18nFramework

从 `@ai-i18n/vite` 导入：

```ts
import type { AiI18nFramework } from '@ai-i18n/vite';
```

## 定义

```ts
type AiI18nFramework = 'vanilla' | 'vue' | 'react';
```

## 值

三种模式都提供 `t()`、`setLang()`、`getLang()`、`getLangs()`、`getLangLoadState()` 与
`subscribe()`。框架模式决定 `virtual:ai-i18n` 额外提供的适配 API：

| 值           | 额外导出                                                |
| ----------- | --------------------------------------------------- |
| `'vanilla'` | 无                                                   |
| `'vue'`     | `useI18n()`、`tRef()`、`i18nComputed()`、`tComputed()` |
| `'react'`   | React `useI18n()`                                   |

省略 [`AiI18nOptions.framework`](/ai-i18n/api/vite/interfaces/ai-i18n-options.md) 时，插件根据最终 Vite
插件列表自动检测。一个 build 同时包含 Vue 与 React 插件时会报错。



---
url: https://bosens-china.github.io/ai-i18n/api/vite/type-aliases/lang-load-state.md
---

# LangLoadState

从 `@ai-i18n/vite` 导入类型：

```ts
import type { LangLoadState } from '@ai-i18n/vite';
```

## 定义

```ts
type LangLoadState =
  | Readonly<{ status: 'idle'; targetLang: null; error: null }>
  | Readonly<{ status: 'loading'; targetLang: string; error: null }>
  | Readonly<{ status: 'error'; targetLang: string; error: unknown }>;
```

## 语义

| `status`  | `targetLang` | `error`   | 含义             |
| --------- | ------------ | --------- | -------------- |
| `idle`    | `null`       | `null`    | 当前没有语言资源等待或错误。 |
| `loading` | `string`     | `null`    | 正在加载指定目标语言。    |
| `error`   | `string`     | `unknown` | 指定目标语言加载失败。    |

快照及其字段只读。`error` 保留 loader reject 的原始值，可能是 falsy；判断失败必须使用
`status === 'error'`。应用应在展示前把详情映射为自己的用户文案。
读取方式见 [`getLangLoadState()`](/ai-i18n/api/runtime/functions/get-lang-load-state.md)，Vue / React 的
响应式派生值分别见 [Vue `useI18n()`](/ai-i18n/api/runtime/vue/use-i18n.md) 和
[React `useI18n()`](/ai-i18n/api/runtime/react/use-i18n.md)。



---
url: https://bosens-china.github.io/ai-i18n/api/vite/type-aliases/message-tree.md
---

# MessageTree

从 `@ai-i18n/vite` 导入类型：

```ts
import type { MessageTree, MessageTreeValue } from '@ai-i18n/vite';
```

## 定义

```ts
type MessageTreeValue =
  | string
  | number
  | boolean
  | bigint
  | null
  | undefined
  | readonly MessageTreeValue[]
  | { readonly [key: string]: MessageTreeValue };

type MessageTree =
  readonly MessageTreeValue[] | { readonly [key: string]: MessageTreeValue };
```

每个字符串叶子都是待翻译文案；其他基础类型原样保留。运行时只接受普通对象和数组，不支持
`Map`、`Set`、函数、getter 或循环引用。调用 `t(messages)` 或 Vue `tRef(messages)` 时，
静态本地或导入对象不要求显式标注该类型，也不要求 `as const`。



---
url: https://bosens-china.github.io/ai-i18n/api/vite/type-aliases/translated-message-tree.md
---

# TranslatedMessageTree

从 `@ai-i18n/vite` 导入类型：

```ts
import type { TranslatedMessageTree } from '@ai-i18n/vite';
```

## 定义

```ts
type TranslatedMessageTree<T> = T extends string
  ? string
  : T extends readonly unknown[]
    ? { [K in keyof T]: TranslatedMessageTree<T[K]> }
    : T extends object
      ? { [K in keyof T]: TranslatedMessageTree<T[K]> }
      : T;
```

该类型递归保留对象、数组和非字符串叶子的结构，只把字符串叶子映射为译文字符串。
[`t()`](/ai-i18n/api/runtime/functions/t.md) 返回该结构的当前快照；Vue
[`tRef()`](/ai-i18n/api/runtime/vue/t-ref.md) 返回包含该结构的只读计算属性。



---
url: https://bosens-china.github.io/ai-i18n/api/vite/type-aliases/translator.md
---

# Translator

从 `@ai-i18n/vite` 导入：

```ts
import type { Translator } from '@ai-i18n/vite';
```

## 定义

```ts
type Translator = ((
  batch: TranslationBatch,
) => Promise<readonly TranslationResult[]>) & {
  reportBatchEvent?: (event: TranslationBatchEvent) => void | Promise<void>;
};
```

## 契约

Translator 返回的数组必须与 `batch.messages` 等长。每一行必须且只能包含
`batch.locales` 中的语言键，值为译文或 `null`。输入和输出通过数组下标对应，不需要返回
message ID。

`reportBatchEvent` 是可选的旁路诊断接收器。Vite 会报告 `scheduled`、`state-applied`、
`persisted` 或 `failed`；接收器缺失、同步抛错或异步拒绝都不会改变翻译与 Build 结果。实现日志
Provider 时可用同一 `batchId` 把这些事件和模型请求关联起来。普通函数 Translator 不需要实现它。

## 示例

```ts
import type { Translator } from '@ai-i18n/vite';

export const translator: Translator = async ({ locales, messages }) =>
  messages.map((message) =>
    Object.fromEntries(
      locales.map((locale) => [locale, translate(locale, message.source)]),
    ),
  );
```

实现 Translator 时必须自行处理鉴权、超时和供应商返回值，再按上述契约返回结果。

相关类型：

- [`TranslationBatch`](/ai-i18n/api/vite/interfaces/translation-batch.md)
- [`TranslationBatchEvent`](/ai-i18n/api/vite/interfaces/translation-batch-event.md)
- [`TranslationMessage`](/ai-i18n/api/vite/interfaces/translation-message.md)
- [`TranslationResult`](/ai-i18n/api/vite/type-aliases/translation-result.md)



---
url: https://bosens-china.github.io/ai-i18n/api/vite/type-aliases/translation-result.md
---

# TranslationResult

从 `@ai-i18n/vite` 导入：

```ts
import type { TranslationResult } from '@ai-i18n/vite';
```

## 定义

```ts
type TranslationResult = Readonly<Record<string, string | null>>;
```

键必须与当前 [`TranslationBatch.locales`](/ai-i18n/api/vite/interfaces/translation-batch.md) 完全一致。
任意字符串（包括空字符串）都是有效译文；`null` 表示该目标语言仍缺译。Runtime 只对 `null` 或
缺失字段回退 source 文案。

```ts
const result: TranslationResult = {
  'en-US': 'Save',
  'ja-JP': null,
};
```

Translator 返回值中缺少语言键、包含额外键，或使用非字符串且非 `null` 的值时，Vite 会拒绝
该批结果。



---
url: https://bosens-china.github.io/ai-i18n/api/vite/type-aliases/translation-batch-stage.md
---

# TranslationBatchStage

从 `@ai-i18n/vite` 导入：

```ts
import type { TranslationBatchStage } from '@ai-i18n/vite';
```

## 定义

```ts
type TranslationBatchStage =
  'scheduled' | 'state-applied' | 'persisted' | 'failed';
```

各阶段含义见 [`TranslationBatchEvent`](/ai-i18n/api/vite/interfaces/translation-batch-event.md)。



---
url: https://bosens-china.github.io/ai-i18n/api/vite/type-aliases/translation-logging.md
---

# TranslationLogging

从 `@ai-i18n/vite` 导入：

```ts
import type { TranslationLogging } from '@ai-i18n/vite';
```

## 定义

```ts
type TranslationLogging = false | string;
```

Vite 会把用户配置的 `provider.logging` 规范化后传给 Translator：关闭时为 `false`，开启时为基于
Vite root 解析后的绝对目录。自定义 Translator 可以忽略该诊断字段；它不参与消息身份、缓存键或
Translation Memory。实现了 `reportBatchEvent` 时，无论此值是否为 `false`，都会收到生命周期事件。



---
url: https://bosens-china.github.io/ai-i18n/api/vitest/functions/ai-i18n-vitest.md
---

# aiI18nVitest()

从 `@ai-i18n/vite/vitest` 导入：

```ts
import { aiI18nVitest } from '@ai-i18n/vite/vitest';
```

## 签名

```ts
function aiI18nVitest(options: AiI18nVitestOptions): Plugin;
```

`aiI18nVitest()` 返回一个 Vite 插件。它解析 `virtual:ai-i18n`，并提供只驻留在内存中的测试
Runtime。

## 行为

- 保留生产环境的 `t()`、`setLang()`、`getLangLoadState()`、框架 `useI18n()` 与 Vue-only
  `tRef()` 契约；
- `autoImport: true` 时注入与生产框架模式相同的 Runtime API；
- 消除 `defineI18nMessages()` 编译宏；
- 不提取翻译；
- 不调用 Provider；
- 不读取或写入 `i18n/` 协议文件。

测试 Runtime 没有目标语言译文，因此 `t()` 始终返回 source 文案。
它也不创建语言 chunk loader，因此 `getLangLoadState()` 与 `useI18n()` 的加载状态字段固定
为 `idle`；这里只保留 API 形状，不模拟生产加载失败。

## 示例

```ts
import { aiI18nVitest } from '@ai-i18n/vite/vitest';
import { defineConfig } from 'vitest/config';

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

完整配置方式见[测试（Vitest）](/ai-i18n/guide/quality/testing.md)。



---
url: https://bosens-china.github.io/ai-i18n/api/vitest/type-aliases/ai-i18n-vitest-options.md
---

# AiI18nVitestOptions

从 `@ai-i18n/vite/vitest` 导入：

```ts
import type { AiI18nVitestOptions } from '@ai-i18n/vite/vitest';
```

## 定义

```ts
type AiI18nVitestOptions = Pick<
  AiI18nOptions,
  | 'sourceLang'
  | 'defaultLang'
  | 'locales'
  | 'framework'
  | 'persist'
  | 'autoImport'
>;
```

## 字段

| 字段            | 必填 | 说明                                |
| ------------- | -- | --------------------------------- |
| `sourceLang`  | 是  | 测试源码使用的语言。                        |
| `locales`     | 是  | Runtime 支持的语言列表。                  |
| `defaultLang` | 否  | 没有有效持久化值时使用的初始语言。                 |
| `framework`   | 否  | 覆盖 Vanilla、Vue 或 React 的自动检测结果。   |
| `persist`     | 否  | 测试 Runtime 的 localStorage 语言偏好配置。 |
| `autoImport`  | 否  | 注入与生产框架模式相同的未绑定 Runtime API。      |

`html`、`loading`、`cache`、`provider`、`directory`、`dts` 等构建期字段不属于该类型。

完整字段契约见 [`AiI18nOptions`](/ai-i18n/api/vite/interfaces/ai-i18n-options.md)。



---
url: https://bosens-china.github.io/ai-i18n/api/runtime/overview.md
---

# Runtime 概览

Runtime API 从 `virtual:ai-i18n` 导入。显式导入始终可用，不受 `autoImport` 影响。

```ts
import {
  getLang,
  getLangLoadState,
  getLangs,
  setLang,
  subscribe,
  t,
} from 'virtual:ai-i18n';
```

`t()` 除了字符串和 tagged template，也可以一次翻译整棵静态文案对象或数组。Vue setup
可以使用 `tRef()` 创建响应式翻译 Ref；纯 Options API 使用 `i18nComputed()` 和
`tComputed()`。

## 可用范围

| API                                                                           | Vanilla | Vue | React | 自动导入    |
| ----------------------------------------------------------------------------- | ------- | --- | ----- | ------- |
| [`t()`](/ai-i18n/api/runtime/functions/t.md)                                  | 是       | 是   | 是     | 全部模式    |
| [`setLang()`](/ai-i18n/api/runtime/functions/set-lang.md)                     | 是       | 是   | 是     | 全部模式    |
| [`getLang()`](/ai-i18n/api/runtime/functions/get-lang.md)                     | 是       | 是   | 是     | 全部模式    |
| [`getLangs()`](/ai-i18n/api/runtime/functions/get-langs.md)                   | 是       | 是   | 是     | 全部模式    |
| [`getLangLoadState()`](/ai-i18n/api/runtime/functions/get-lang-load-state.md) | 是       | 是   | 是     | 全部模式    |
| [`subscribe()`](/ai-i18n/api/runtime/functions/subscribe.md)                  | 是       | 是   | 是     | 全部模式    |
| [Vue `useI18n()`](/ai-i18n/api/runtime/vue/use-i18n.md)                       | 否       | 是   | 否     | 仅 Vue   |
| [React `useI18n()`](/ai-i18n/api/runtime/react/use-i18n.md)                   | 否       | 否   | 是     | 仅 React |
| [`tRef()`](/ai-i18n/api/runtime/vue/t-ref.md)                                 | 否       | 是   | 否     | 仅 Vue   |
| [`i18nComputed()`](/ai-i18n/api/runtime/vue/i18n-computed.md)                 | 否       | 是   | 否     | 仅 Vue   |
| [`tComputed()`](/ai-i18n/api/runtime/vue/t-computed.md)                       | 否       | 是   | 否     | 仅 Vue   |

Vue 业务组件可以在 template、render、computed 与 Options method 中直接调用顶层 `t()`；
Vue 适配器会追踪语言 revision。React 业务组件使用 `useI18n()` 建立订阅。`getLang()` 和
`getLangLoadState()` 仍是调用时快照；普通模块应在函数或 getter 中按需调用，避免在模块
初始化时保存不会刷新的值。

Vue 开启 `autoImport: true` 后，script 与 template 都可以直接使用裸 `t()`，生成声明会提供
IDE 类型。关闭自动导入时，`<script setup>` 的显式 import 会自然暴露给 template；纯
Options 的普通 `<script>` import 如需用于 template，还要通过真实组件 binding 暴露。完整
边界见[自动导入](/ai-i18n/guide/basic/auto-import.md)。

Vue setup 中需要预先声明响应式 label 或文案树时，可使用 `tRef()`；它按输入返回只读
`ComputedRef<string>` 或同形文案树。纯 Options API 把 `i18nComputed()` 展开到组件
`computed`，并用 `tComputed()` 创建相同能力的翻译 getter。React 与 Vanilla 不提供这些
Vue 专用 API。

[`defineI18nMessages()`](/ai-i18n/api/runtime/macros/define-i18n-messages.md) 是编译宏，不是 Runtime
导出，因此无需 import。



---
url: https://bosens-china.github.io/ai-i18n/api/runtime/functions/t.md
---

# t()

从 `virtual:ai-i18n` 导入：

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

## 签名

```ts
function t(source: string, options?: TranslationOptions): string;
function t(strings: TemplateStringsArray, ...values: unknown[]): string;
function t<T extends MessageTree>(messages: T): TranslatedMessageTree<T>;
```

## 参数

| 参数        | 类型                                                                          | 必填 | 作用                   |
| --------- | --------------------------------------------------------------------------- | -- | -------------------- |
| `source`  | `string`                                                                    | 是  | 源文案，也是缺译时的回退值。       |
| `options` | [`TranslationOptions`](/ai-i18n/api/vite/interfaces/translation-options.md) | 否  | 通过 `comment` 补充翻译语境。 |

source 与 options 必须能在构建期静态求值。

```ts
t('保存');
t('保存', { comment: '按钮' });
t('提交', { comment: '创建 Git 提交' });
```

## 文案树

整棵静态对象或数组可以直接传给 `t()`。每个字符串叶子都会翻译，返回值保持原有结构；
数字、布尔值、`bigint`、`null` 与 `undefined` 原样保留：

```ts
// messages.ts
export const messages = {
  actions: {
    save: '保存',
    cancel: '取消',
  },
  states: ['等待中', '处理中'],
  maxRetries: 3,
};

// React 组件或普通模块
const labels = t(messages);
// labels.actions.save: string
// labels.states: string[]
// labels.maxRetries: number
```

本地或导入的静态 `const` 都可以使用，不需要 `as const`，也不需要
`defineI18nMessages()`。文案树应当是纯文案结构：只使用普通对象、数组和上述叶子值；
不要混入路由、业务 key 等不应翻译的字符串，也不支持 `Map`、`Set`、函数、循环引用、
getter 或其他运行时结果。

整棵树调用不能为单个叶子设置 `comment`，也不能在叶子中使用 tagged template 插值。
需要成员级语境或动态索引时，改用
[`defineI18nMessages()`](/ai-i18n/api/runtime/macros/define-i18n-messages.md) 后逐项调用 `t()`。

相同原文搭配不同的 `comment` 会作为不同语境分别翻译。没有 `comment` 时，同一原文默认共享译文。

## Tagged template

动态值使用 tagged template：

```ts
t`你好 ${user.name}，你有 ${unreadCount} 条消息`;
```

表达式会变成 `{{0}}`、`{{1}}` 等占位符，不会交给翻译模型。译文可以调整占位符顺序，
Runtime 会在展示前填入原始值。

Runtime 会比较源文与译文的占位符。译文缺少、多出或改变编号时，浏览器输出 warning，
但仍继续使用该译文。

## 返回值

字符串调用返回当前语言的译文；译文缺失或值为 `null` 时返回 source 文案。文案树调用返回
形状相同的新对象或数组，其中每个字符串叶子按相同规则翻译；不会修改输入值。

:::warning 不要长期保存译后字符串
已经写入 state、storage、请求体或文件元数据的字符串不会随语言切换更新。持久数据和业务判断
应保存稳定的语义 code、序号或消息标识，并在展示层调用 `t()`。模块初始化时的
`const label = t('保存')` 也是一次性快照；普通模块可改为
`const getLabel = () => t('保存')`。
:::

Vue 模式的顶层 `t` 会追踪 adapter revision，因此可以在 template、render、computed 与
Options method 中直接使用。React 组件应使用
[React `useI18n()`](/ai-i18n/api/runtime/react/use-i18n.md) 建立语言变化订阅。对应 ESLint 生命周期
检查见 [ESLint](/ai-i18n/guide/quality/eslint.md)。

Vue setup 中需要预先声明响应式 label 时，使用 Vue-only
[`tRef()`](/ai-i18n/api/runtime/vue/t-ref.md)；纯 Options 的 `computed` 使用
[`tComputed()`](/ai-i18n/api/runtime/vue/t-computed.md)。`t()` 的字符串输入返回字符串，文案树输入
返回翻译后的同形结构；两者都不会因为调用位置不同而变成 Ref。

支持的文案写法见[通用文案写法](/ai-i18n/guide/basic/static-analysis/common.md)。



---
url: https://bosens-china.github.io/ai-i18n/api/runtime/functions/set-lang.md
---

# setLang()

从 `virtual:ai-i18n` 导入：

```ts
import { setLang } from 'virtual:ai-i18n';
```

## 签名

```ts
function setLang(value: string): Promise<void>;
```

## 参数

`value` 必须匹配 [`AiI18nOptions.locales`](/ai-i18n/api/vite/interfaces/ai-i18n-options.md) 中的某个
`value`。不支持的值会抛出 `RangeError`。

## 行为

没有启用语言分包时，Runtime 会立即提交切换。启用 `loading` 后，Runtime 先加载目标语言
chunk，再切换语言并通知订阅者。

相同 locale 的并发调用会复用同一次底层语言包加载请求，但不保证各次 `setLang()` 返回的
Promise 引用相等。不同 locale 的并发切换以最后一次调用为准。
加载失败时 Promise 会 reject，当前语言保持不变，并通过
[`getLangLoadState()`](/ai-i18n/api/runtime/functions/get-lang-load-state.md) 暴露 error 快照。
共享状态不会消费 rejected Promise；即使 UI 只读取内置 error 状态，调用方仍需
`await` + `catch` 或显式 `.catch()`，避免 unhandled rejection。

配置 `persist` 后，切换成功的语言会写入 localStorage。

## 示例

```ts
try {
  await setLang('en-US');
} catch {
  // 仅在需要业务级恢复动作时处理；通用 loading/error UI 可直接读取共享状态。
}
```

按需加载的完整示例见[语言分包与按需加载](/ai-i18n/guide/basic/locale-loading.md)。



---
url: https://bosens-china.github.io/ai-i18n/api/runtime/functions/get-lang.md
---

# getLang()

从 `virtual:ai-i18n` 导入：

```ts
import { getLang } from 'virtual:ai-i18n';
```

## 签名

```ts
function getLang(): string;
```

## 返回值

返回当前语言的 `value`。

首次加载按“有效持久化值 → `defaultLang`”选择。启用按 locale 分包时，目标语言资源就绪前
暂时返回 `sourceLang`。

`getLang()` 本身不建立框架响应式依赖。Vue Composition 组件应使用
[Vue `useI18n()`](/ai-i18n/api/runtime/vue/use-i18n.md)，纯 Options 组件使用
[`i18nComputed()`](/ai-i18n/api/runtime/vue/i18n-computed.md)，React 组件使用
[React `useI18n()`](/ai-i18n/api/runtime/react/use-i18n.md) 返回的 `currentLang`。



---
url: https://bosens-china.github.io/ai-i18n/api/runtime/functions/get-langs.md
---

# getLangs()

从 `virtual:ai-i18n` 导入：

```ts
import { getLangs } from 'virtual:ai-i18n';
```

## 签名

```ts
function getLangs(): readonly LangOption[];
```

## 返回值

返回 [`AiI18nOptions.locales`](/ai-i18n/api/vite/interfaces/ai-i18n-options.md) 的快照。每一项都包含必填的
`value` 与 `label`。

修改返回的对象不会改变 Runtime 内部配置。

```ts
for (const locale of getLangs()) {
  console.log(locale.value, locale.label);
}
```

字段定义见 [`LangOption`](/ai-i18n/api/vite/interfaces/lang-option.md)。



---
url: https://bosens-china.github.io/ai-i18n/api/runtime/functions/get-lang-load-state.md
---

# getLangLoadState()

从 `virtual:ai-i18n` 导入：

```ts
import { getLangLoadState } from 'virtual:ai-i18n';
```

## 签名

```ts
function getLangLoadState(): LangLoadState;

type LangLoadState =
  | { status: 'idle'; targetLang: null; error: null }
  | { status: 'loading'; targetLang: string; error: null }
  | { status: 'error'; targetLang: string; error: unknown };
```

## 返回值

返回当前不可变快照：

- `idle`：当前没有等待中的语言资源，也没有保留的最近加载错误；
- `loading`：正在为 `targetLang` 加载资源；
- `error`：`targetLang` 加载失败，原始异常保存在 `error`。

loader 可以 reject 任意 JavaScript 值，所以 `error` 可能是 falsy。请用
`status === 'error'` 判断失败，不要用 `if (state.error)`。

新的有效语言切换开始时会清除上一条错误。加载成功后恢复 `idle`。不同语言并发切换遵循
last-call-wins，过期请求的完成或失败不会覆盖较新的快照。

## 订阅变化

函数本身只读取一次快照。Vanilla 应用可通过 [`subscribe()`](/ai-i18n/api/runtime/functions/subscribe.md) 监听变化后重新
读取：

```ts
import { getLangLoadState, setLang, subscribe } from 'virtual:ai-i18n';

const unsubscribe = subscribe(() => {
  renderLanguageStatus(getLangLoadState());
});

// 即使 UI 读取共享 error state，也要终结 setLang() 的 rejected Promise。
void setLang('en-US').catch(() => {});
```

Vue Composition 与 React 组件通常分别使用 [Vue `useI18n()`](/ai-i18n/api/runtime/vue/use-i18n.md) 或
[React `useI18n()`](/ai-i18n/api/runtime/react/use-i18n.md) 返回的响应式状态。纯 Vue Options 组件使用
[`i18nComputed()`](/ai-i18n/api/runtime/vue/i18n-computed.md)。



---
url: https://bosens-china.github.io/ai-i18n/api/runtime/functions/subscribe.md
---

# subscribe()

从 `virtual:ai-i18n` 导入：

```ts
import { subscribe } from 'virtual:ai-i18n';
```

## 签名

```ts
function subscribe(listener: () => void): () => void;
```

## 参数

`listener` 是无参数回调。语言、语言加载状态或 Runtime 模块更新时，Runtime 会执行该回调。

## 返回值

返回取消订阅函数：

```ts
const unsubscribe = subscribe(render);

unsubscribe();
```

Vue 与 React 组件通常不需要直接订阅。Vue Composition 使用
[`useI18n()`](/ai-i18n/api/runtime/vue/use-i18n.md)，纯 Options 使用
[`i18nComputed()`](/ai-i18n/api/runtime/vue/i18n-computed.md)，React 使用
[`useI18n()`](/ai-i18n/api/runtime/react/use-i18n.md)。



---
url: https://bosens-china.github.io/ai-i18n/api/runtime/vue/use-i18n.md
---

# Vue useI18n()

Vue 模式从 `virtual:ai-i18n` 导出 `useI18n()`：

```ts
import { useI18n } from 'virtual:ai-i18n';
```

## 签名

```ts
interface VueI18n {
  t: I18nRuntime['t'];
  setLang: I18nRuntime['setLang'];
  currentLang: ComputedRef<string>;
  langs: DeepReadonly<ShallowRef<readonly LangOption[]>>;
  langLoadState: ComputedRef<LangLoadState>;
  isLangLoading: ComputedRef<boolean>;
  langLoadError: ComputedRef<unknown | null>;
}

type UseI18n = () => VueI18n;
```

`useI18n()` 没有参数。

## 返回值

| 字段              | 类型                                                | 作用            |
| --------------- | ------------------------------------------------- | ------------- |
| `t`             | `I18nRuntime['t']`                                | 与顶层导出相同的翻译函数  |
| `setLang`       | `I18nRuntime['setLang']`                          | 切换语言          |
| `currentLang`   | `ComputedRef<string>`                             | 当前语言          |
| `langs`         | `DeepReadonly<ShallowRef<readonly LangOption[]>>` | 支持的语言列表       |
| `langLoadState` | `ComputedRef<LangLoadState>`                      | 完整的响应式加载状态    |
| `isLangLoading` | `ComputedRef<boolean>`                            | 是否正在加载目标语言    |
| `langLoadError` | `ComputedRef<unknown \| null>`                    | 最近一次有效切换的加载错误 |

`langLoadError` 保留 loader reject 的原始值，因此类型是 `unknown`，也可能是
`undefined`、`null`、空字符串等 falsy 值。判断是否失败必须使用
`langLoadState.status === 'error'`。`langLoadError` 只用于读取详情，展示前应转换为应用
自己的用户文案。下一次有效切换开始或加载成功后会清除它。完整三态见
[`getLangLoadState()`](/ai-i18n/api/runtime/functions/get-lang-load-state.md)。

## `t` 与顶层导出的关系

新代码推荐直接导入 `t`，让翻译函数的来源一眼可见。需要语言状态时，再让 `useI18n()` 提供
对应的 Ref 和 action：

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

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

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

`useI18n()` 仍返回 `t`。既有解构写法，以及自动导入模式下希望保持零 ai-i18n import 的
写法，都可以继续使用：

```vue
<script setup lang="ts">
const { t } = useI18n();
</script>

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

这里的 `t` 与顶层导出是同一个函数，不是 Ref，因此不需要 `.value`，也不是即将废弃的
兼容分支。Vue adapter 统一维护共享 revision；template、render 或 computed 调用 `t()`
时，Vue 会收集这项依赖。翻译刷新不依赖每个组件调用 `useI18n()` 后再建立一份组件级订阅。

不要在 setup 阶段提前保存译后字符串：

```ts
const label = t('保存'); // 只计算一次，不会随语言切换更新
```

需要在脚本中预先声明响应式展示值时，使用 [`tRef()`](/ai-i18n/api/runtime/vue/t-ref.md)：

```ts
import { tRef } from 'virtual:ai-i18n';

const label = tRef('保存');
```

`tRef` 是独立的 Vue API，不在 `useI18n()` 返回值中。对象或数组展示值也可以直接写
`const labels = tRef(messages)`，得到随语言变化更新的同形只读计算属性。

## 示例

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

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

async function switchLanguage() {
  try {
    await setLang('en-US');
  } catch {
    // 通用错误 UI 读取共享状态；这里终结 rejected Promise。
  }
}
</script>

<template>
  <button :disabled="isLangLoading" @click="switchLanguage">
    {{ isLangLoading ? t('正在加载语言包…') : t('切换语言') }}
  </button>
  <p v-if="langLoadState.status === 'error'">
    {{ t('语言包加载失败，请重试') }}
  </p>
</template>
```

建议在 `<script setup>` 或 `setup()` 中调用。静态提取规则见
[Vue 文案写法](/ai-i18n/guide/basic/static-analysis/vue.md)。完全不使用 `setup()` 的 Options 组件
改用 [`i18nComputed()`](/ai-i18n/api/runtime/vue/i18n-computed.md)；它提供相同的状态字段，但在 Options 中直接读取
解包后的值。



---
url: https://bosens-china.github.io/ai-i18n/api/runtime/vue/t-ref.md
---

# tRef()

`tRef()` 是 Vue 模式专用的语法糖，从 `virtual:ai-i18n` 直接导入：

```ts
import { tRef } from 'virtual:ai-i18n';
```

`tRef` 不属于 `useI18n()` 的返回值。

## 签名

```ts
function tRef(
  source: string,
  options?: TranslationOptions,
): ComputedRef<string>;
function tRef(
  strings: TemplateStringsArray,
  ...values: unknown[]
): ComputedRef<string>;
function tRef<T extends MessageTree>(
  messages: T,
): ComputedRef<TranslatedMessageTree<T>>;
```

字符串输入返回 Vue 的只读 `ComputedRef<string>`；文案树输入返回保持原结构的
`ComputedRef<TranslatedMessageTree<T>>`。语言或 Runtime 翻译模块更新后，`value` 会重新
计算；tagged template 插值如果是 Vue Ref，也会在 `computed` 内解包并建立依赖。

source 与 options 的静态提取要求和 [`t()`](/ai-i18n/api/runtime/functions/t.md) 相同。除普通文本和
整棵文案树外，也可以把 `defineI18nMessages()` 标记后的成员传给 `tRef()`：

```ts
const messages = defineI18nMessages({
  actions: { save: '保存', cancel: '取消' },
});

const saveLabel = tRef(messages.actions.save);
```

`defineI18nMessages()` 是编译宏，无需 import；只有按属性或索引选择单条文案时才需要它。

## setup 中的展示值

当脚本逻辑需要复用一个响应式 label 时，可以直接写：

```vue
<script setup lang="ts">
import { shallowRef } from 'vue';
import { tRef } from 'virtual:ai-i18n';

const name = shallowRef('Ada');
const saveLabel = tRef('保存');
const greeting = tRef`你好 ${name}`;

function submit() {
  console.log(saveLabel.value);
}
</script>

<template>
  <button>{{ saveLabel }}</button>
  <p>{{ greeting }}</p>
</template>
```

在脚本中读取 `.value`；模板会自动解包 Ref。

## 响应式对象与数组

需要在 setup 中复用一组会随语言切换更新的文案时，可以直接把静态文案树交给 `tRef()`：

```vue
<script setup lang="ts">
import { tRef } from 'virtual:ai-i18n';
import { messages } from './messages';

const labels = tRef(messages);
</script>

<template>
  <button>{{ labels.actions.save }}</button>
  <span>{{ labels.states[0] }}</span>
</template>
```

静态本地对象和导入对象都支持，不要求 `as const` 或 `defineI18nMessages()`。每个字符串叶子
都会翻译，其他基础类型原样保留。输入必须是纯文案的普通对象或数组；不支持 `Map`、`Set`、
函数、循环引用、getter、运行时生成的集合，也不能为单个叶子设置 `comment` 或插值。

## 与 `t()` 的分工

- 模板或渲染函数当场展示：直接使用 [`t()`](/ai-i18n/api/runtime/functions/t.md)。
- Vue setup / composable 需要预先声明响应式字符串、对象或数组：使用 `tRef()`。
- 纯 Options API 的 computed：使用 [`tComputed()`](/ai-i18n/api/runtime/vue/t-computed.md)。
- 事件、日志或普通工具函数需要即时字符串：使用 `t()`。

不要在 template 或渲染函数中直接调用 `tRef()`：

```vue
<!-- 错误：每次渲染都创建新的 computed -->
<template>{{ tRef('保存') }}</template>
```

应在 setup 中创建一次，再把返回的 Ref 用于模板。对应生命周期问题由
[`ai-i18n/no-unsubscribed-t`](/ai-i18n/guide/quality/eslint-rules.md) 提示。静态提取规则见
[Vue 文案写法](/ai-i18n/guide/basic/static-analysis/vue.md)。



---
url: https://bosens-china.github.io/ai-i18n/api/runtime/vue/i18n-computed.md
---

# i18nComputed()

`i18nComputed()` 是 Vue 模式专用的 Options API 配置工厂：

```ts
import { i18nComputed } from 'virtual:ai-i18n';
```

它不创建组件，也不要求 `setup()`。把返回值展开到组件的 `computed`，Vue 会为每个组件
实例创建和清理对应的 computed watcher。

## 签名

```ts
function i18nComputed(): {
  currentLang(): string;
  langs(): readonly LangOption[];
  langLoadState(): LangLoadState;
  isLangLoading(): boolean;
  langLoadError(): unknown | null;
};
```

返回值与 [`useI18n()`](/ai-i18n/api/runtime/vue/use-i18n.md) 表示同一份 Runtime 状态，但 Options computed 中读取的是
已经解包的值，不需要 `.value`。

## 基本用法

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

export default defineComponent({
  computed: {
    ...i18nComputed(),

    currentLanguageLabel() {
      return (
        this.langs.find(({ value }) => value === this.currentLang)?.label ??
        this.currentLang
      );
    },
  },

  watch: {
    currentLang(next: string, previous: string) {
      console.log(previous, '->', next);
    },
  },

  methods: {
    async switchLanguage(event: Event) {
      const target = event.currentTarget;
      if (!(target instanceof HTMLSelectElement)) return;
      await setLang(target.value);
    },
  },
});
</script>

<template>
  <select :value="currentLang" @change="switchLanguage">
    <option v-for="lang in langs" :key="lang.value" :value="lang.value">
      {{ lang.label }}
    </option>
  </select>

  <p>{{ currentLanguageLabel }}</p>
  <p v-if="isLangLoading">正在加载</p>
  <p v-else-if="langLoadState.status === 'error'">语言包加载失败</p>
</template>
```

Options `watch` 由 Vue 管理生命周期，组件卸载时会自动清理。组件外的长期监听仍使用
[`subscribe()`](/ai-i18n/api/runtime/functions/subscribe.md)。

## TypeScript 与 IDE 提示

TypeScript 组件使用 `defineComponent()`。Vue 自身的 Options `watch` 类型不会根据被监听
的 key 推断回调参数，因此应像上例一样显式标注 `next` 和 `previous`。自动导入的声明文件、
组件实例类型和常见错误统一见
[TypeScript 与生成声明](/ai-i18n/guide/quality/typescript.md)。

## 同名 computed

展开后声明的同名字段会覆盖默认 getter：

```ts
computed: {
  ...i18nComputed(),
  currentLang() {
    return 'custom';
  },
},
```

除非组件确实需要替换产品语义，否则不要覆盖这些字段。

`langLoadError` 保留 loader reject 的原始值。判断加载是否失败时，以
`langLoadState.status === 'error'` 为准；展示前应转换为应用自己的用户文案。



---
url: https://bosens-china.github.io/ai-i18n/api/runtime/vue/t-computed.md
---

# tComputed()

`tComputed()` 是 Vue 模式专用的 Options API 翻译 getter 工厂：

```ts
import { tComputed } from 'virtual:ai-i18n';
```

它与 [`tRef()`](/ai-i18n/api/runtime/vue/t-ref.md) 支持相同的静态文案输入，但返回 Options `computed` 接受的 getter，
而不是 `ComputedRef`。

## 签名

```ts
function tComputed(source: string, options?: TranslationOptions): () => string;
function tComputed(
  strings: TemplateStringsArray,
  ...values: unknown[]
): () => string;
function tComputed<T extends MessageTree>(
  messages: T,
): () => TranslatedMessageTree<T>;
```

## 基本用法

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

export default defineComponent({
  computed: {
    saveLabel: tComputed('保存'),
    labels: tComputed({
      save: '保存',
      cancel: '取消',
    }),
  },
});
</script>

<template>
  <button>{{ saveLabel }}</button>
  <button>{{ labels.cancel }}</button>
</template>
```

语言或翻译模块变化后，Vue 会使这些 computed 失效并在下次读取时重新计算。每个组件实例拥有
自己的 computed 缓存。

## 动态组件状态

如果插值依赖 `data`、props 或其他 `this` 属性，直接编写普通 computed，并在 getter 中调用
[`t()`](/ai-i18n/api/runtime/functions/t.md)：

```ts
computed: {
  greeting() {
    return t`你好 ${this.name}`;
  },
},
```

## 使用位置

`tComputed()` 应直接作为 Options computed 的值：

```ts
computed: {
  label: tComputed('保存'),
},
```

不要在 `data()`、template 或 render 函数中调用：

```ts
data() {
  return {
    label: tComputed('保存'), // 得到的是 getter，不是译文
  };
},
```

```vue
<!-- 错误：页面得到的是 getter -->
<template>{{ tComputed('保存') }}</template>
```

setup 和 composable 使用 [`tRef()`](/ai-i18n/api/runtime/vue/t-ref.md)；template、render 或手写 computed getter
当场展示时直接使用 [`t()`](/ai-i18n/api/runtime/functions/t.md)。



---
url: https://bosens-china.github.io/ai-i18n/api/runtime/react/use-i18n.md
---

# React useI18n()

React 模式从 `virtual:ai-i18n` 导出 `useI18n()`：

```ts
import { useI18n } from 'virtual:ai-i18n';
```

## 签名

```ts
interface ReactI18n {
  t: I18nRuntime['t'];
  setLang: I18nRuntime['setLang'];
  currentLang: string;
  langs: readonly LangOption[];
  langLoadState: LangLoadState;
  isLangLoading: boolean;
  langLoadError: unknown | null;
}

type UseI18n = () => ReactI18n;
```

`useI18n()` 没有参数。

## 返回值

| 字段              | 类型                       | 作用            |
| --------------- | ------------------------ | ------------- |
| `t`             | `I18nRuntime['t']`       | 翻译文案          |
| `setLang`       | `I18nRuntime['setLang']` | 切换语言          |
| `currentLang`   | `string`                 | 当前语言          |
| `langs`         | `readonly LangOption[]`  | 支持的语言列表       |
| `langLoadState` | `LangLoadState`          | 完整加载状态快照      |
| `isLangLoading` | `boolean`                | 是否正在加载目标语言    |
| `langLoadError` | `unknown \| null`        | 最近一次有效切换的加载错误 |

`langLoadError` 保留 loader reject 的原始值，因此类型是 `unknown`，也可能是
`undefined`、`null`、空字符串等 falsy 值。判断是否失败必须使用
`langLoadState.status === 'error'`。`langLoadError` 只用于读取详情，展示前应转换为应用
自己的用户文案。下一次有效切换开始或加载成功后会清除它。完整三态见
[`getLangLoadState()`](/ai-i18n/api/runtime/functions/get-lang-load-state.md)。

## 解构或改名 `t`

React 可以直接解构或改名 `t`。分析器会识别这个绑定，并按顶层 `t()` 相同的规则提取
普通文本、静态变量、条件表达式、tagged template 和静态文案树：

```tsx
const { t: translate } = useI18n();

const title = translate('订单详情');
const labels = translate({ save: '保存', cancel: '取消' });
```

这里的 `translate` 仍然来自 Hook。解构或改名只改变本地变量名，不会把它降级为无订阅的
Runtime 顶层 `t`。

## 示例

```tsx
import { useI18n } from 'virtual:ai-i18n';

export function LanguagePicker() {
  const { isLangLoading, langLoadState, setLang, t } = useI18n();
  const labels = t({
    loading: '正在加载语言包…',
    switchLanguage: '切换语言',
  });

  async function switchLanguage() {
    try {
      await setLang('en-US');
    } catch {
      // 通用错误 UI 读取共享状态；这里终结 rejected Promise。
    }
  }

  return (
    <>
      <button disabled={isLangLoading} onClick={() => void switchLanguage()}>
        {isLangLoading ? labels.loading : labels.switchLanguage}
      </button>
      {langLoadState.status === 'error' ? (
        <p>{t('语言包加载失败，请重试')}</p>
      ) : null}
    </>
  );
}
```

React 中必须遵守 Hook 调用规则。

React 适配器使用 `useSyncExternalStore` 订阅 Runtime revision。revision 改变时，Hook
返回的 `t` 也会获得新的函数引用，因此 React Compiler 可以使依赖该引用的缓存失效。直接
导入 Runtime 顶层 `t` 没有这个订阅边界；`"use memo"` 或 `"use no memo"` 都不能替代
`useI18n()`。

文案写法见 [React 文案写法](/ai-i18n/guide/basic/static-analysis/react.md)。



---
url: https://bosens-china.github.io/ai-i18n/api/runtime/macros/define-i18n-messages.md
---

# defineI18nMessages()

`defineI18nMessages()` 是全局编译宏，不是 `virtual:ai-i18n` 的 Runtime 导出，因此无需 import。

## 签名

```ts
function defineI18nMessages<T>(value: T): T;
```

## 用法

```ts
const messages = defineI18nMessages({
  save: '保存',
  states: ['等待中', '处理中', '已完成'],
});

t(messages.save);
t(messages.states[index]);
```

宏用于“先定义集合，再把其中某个成员交给 `t()`”的写法。如果需要一次翻译整棵纯文案对象
或数组，可以直接写 `t(messages)`；Vue setup 中可以写 `tRef(messages)`。这两种整树调用
不需要宏，也不要求 `as const`：

```ts
export const messages = {
  save: '保存',
  states: ['等待中', '处理中'],
};

const labels = t(messages);
```

宏接受任意类型，并在 Vite 或 `aiI18nVitest()` 转换时消除为原参数。它不会冻结、拷贝或校验
对象；作用只是告诉静态分析器，这个对象或数组是可枚举的消息集合。

动态索引会提取集合中可以证明有限的候选值。函数调用、getter、`await` 等用户代码不会在分析
阶段执行。

## 限制

宏必须直接写成 `defineI18nMessages(value)`。不能将它赋值给别名、作为值传递，或在未经
`aiI18n()` / `aiI18nVitest()` 转换的 Node、Jest 环境中执行。

局部声明同名 `defineI18nMessages` 时，局部 binding 优先，不会被识别为编译宏。

插件生成的 `ai-i18n.d.ts` 会提供全局 TypeScript 声明。ESLint 的候选数量检查见
[ESLint](/ai-i18n/guide/quality/eslint.md#static-candidate-limit-选项)。



---
url: https://bosens-china.github.io/ai-i18n/api/openai/functions/open-ai.md
---

# openAI()

从 `@ai-i18n/openai` 导入：

```ts
import { openAI } from '@ai-i18n/openai';
```

## 签名

```ts
function openAI(options: OpenAIOptions): Translator;
```

## 参数

| 参数        | 类型                                                                   | 说明            |
| --------- | -------------------------------------------------------------------- | ------------- |
| `options` | [`OpenAIOptions`](/ai-i18n/api/openai/interfaces/open-ai-options.md) | 模型、服务地址和请求配置。 |

## 返回值

返回 [`Translator`](/ai-i18n/api/vite/type-aliases/translator.md)，可直接传给
[`AiI18nProviderOptions.translator`](/ai-i18n/api/vite/type-aliases/ai-i18n-provider-options.md)。

## 示例

```ts
import { openAI } from '@ai-i18n/openai';

const translator = openAI({
  baseURL: 'https://example.com/v1',
  model: 'model-name',
  apiKey: process.env.AI_API_KEY,
});
```

`openAI()` 对收到的每个批次调用模型一次。目标 locale 分组、批次切分、并发限制和结果写回由
`@ai-i18n/vite` 负责。

每次调用 `openAI()` 都会创建独立的惰性日志 session，但日志默认关闭。Vite 的
`provider.logging` 显式启用后的第一个模型批次才生成文件。Dev/HMR 或 Build Watch 复用同一个
translator 时，后续响应会追加到同一文件。

日志以批次生命周期、REQUEST、RESPONSE、VALIDATION 和 ERROR 块组织。Vite 调度时，同一批次从
BATCH SCHEDULED、REQUEST、RESPONSE、VALIDATION、STATE APPLIED 到 PERSISTED 使用相同
`batchId`；失败则记录 BATCH FAILED。REQUEST 展示实际 messages，RESPONSE 完整保留每个 choice
的 assistant message，包括兼容服务提供的 reasoning、tool calls、refusal 和未知扩展字段，但过滤
SDK runtime 与常规传输噪声。并发调用使用独立异步上下文，日志块不会串到其他批次。

经过 Vite 使用时，设置 `provider.logging: true` 使用 Vite root 下的 `logs/`，也可以用字符串指定
相对或绝对目录。完整阅读方法见
[LLM 日志与排障](/ai-i18n/guide/advanced/llm-logs.md)。

Provider 使用 OpenAI-compatible JSON mode。目标语言和批次长度会生成本批唯一的结构化 Schema；
同一 Schema 同时约束模型输出并校验实际响应，因此返回对象的顶层字段、数组长度、语言键和译文
类型都必须精确匹配，额外字段也会被拒绝。占位符一致性在结构校验后单独检查。模型服务需要支持
Chat Completions 和 `response_format: { type: "json_object" }`。

完整接入流程见 [AI 翻译](/ai-i18n/guide/advanced/ai-translation.md)。



---
url: https://bosens-china.github.io/ai-i18n/api/openai/interfaces/open-ai-options.md
---

# OpenAIOptions

从 `@ai-i18n/openai` 导入：

```ts
import type { OpenAIOptions } from '@ai-i18n/openai';
```

## 定义

```ts
interface OpenAIOptions {
  baseURL: string;
  model: string;
  apiKey?: string;
  temperature?: number;
  maxTokens?: number;
  timeoutMs?: number;
  maxRetries?: number;
  headers?: HeadersInit;
  systemPrompt?: string;
  langSmith?: LangSmithOptions;
}
```

## 字段

| 字段             | 类型                                                                       | 必填 | 默认值       | 约束     | 作用                            |
| -------------- | ------------------------------------------------------------------------ | -- | --------- | ------ | ----------------------------- |
| `baseURL`      | `string`                                                                 | 是  | 无         | 非空     | OpenAI-compatible API 根地址。    |
| `model`        | `string`                                                                 | 是  | 无         | 非空     | 显式选择模型。                       |
| `apiKey`       | `string`                                                                 | 否  | 本地服务使用占位值 | 无      | 请求认证密钥。                       |
| `temperature`  | `number`                                                                 | 否  | `1`       | ≥ 0    | 传给模型的 temperature。            |
| `maxTokens`    | `number`                                                                 | 否  | 由模型决定     | 整数；> 0 | 单次响应 token 上限。                |
| `timeoutMs`    | `number`                                                                 | 否  | `120000`  | 整数；> 0 | 单次请求超时，单位为毫秒。                 |
| `maxRetries`   | `number`                                                                 | 否  | `3`       | 整数；≥ 0 | LangChain 层的最大重试次数。           |
| `headers`      | `HeadersInit`                                                            | 否  | 无         | 无      | 追加到 Provider 请求的 HTTP Header。 |
| `systemPrompt` | `string`                                                                 | 否  | 内置翻译提示词   | 非空     | 覆盖产品领域、术语和风格要求。               |
| `langSmith`    | [LangSmithOptions](/ai-i18n/api/openai/interfaces/lang-smith-options.md) | 否  | 不启用       | 无      | 启用 LangSmith tracing。         |

`baseURL`、`model` 和显式传入的 `systemPrompt` 去除首尾空白后不能为空。`temperature` 必须
大于或等于 `0`；`maxTokens` 与 `timeoutMs` 必须是正整数；`maxRetries` 必须是非负整数。
`headers` 会按标准 `HeadersInit` 解析并规范化。所有配置在创建 Provider 时一次性校验；任一字段
无效都会在模型请求发出前报告具体字段，不会等到 Dev 或 Build 的首个翻译批次才失败。

Provider 不主动读取宿主的 `OPENAI_API_KEY`。密钥必须显式传入；省略时使用本地服务占位值，
避免意外把宿主环境变量发送到其他地址。

## 日志

OpenAI Provider 不提供第二套日志开关。经过 Vite 调用时，只由 `provider.logging` 决定是否记录及
写入目录；默认关闭，`true` 使用 Vite root 下的 `logs/`，字符串可指定相对或绝对目录。

启用后，一个 `openAI()` translator 实例在对应目录使用一个日志文件。同一实例处理多个批次时持续
追加；新建实例会生成带本地日期时间、PID 和序号的新文件。Vite 触发的 BATCH SCHEDULED、REQUEST、RESPONSE、
VALIDATION、STATE APPLIED、PERSISTED 或 BATCH FAILED 块带有同一 `batchId`；并发批次使用各自的
ID。日志完整记录最终发送的 messages，以及每个响应 choice 的 reasoning、assistant content 和
message 扩展字段；同时保留模型、请求 ID、状态、耗时、usage、Provider 校验结果与错误。未设置
请求参数、SDK runtime 字段和常规传输 Header 会被过滤。日志写入失败只警告一次，不改变翻译或
Build 的结果。

日志包含发送给模型的文案和模型输出，应将 `logs/`、`*.log` 或自定义目录加入 `.gitignore`。
显式 API key 由 Provider 脱敏，常见认证 Header 由 OpenAI SDK 脱敏。日志不等同于逐字节 HTTP
抓包，也无法记录服务或 SDK 没有暴露的内部响应正文。

完整阅读与排障方法见 [LLM 日志与排障](/ai-i18n/guide/advanced/llm-logs.md)。

## systemPrompt

`systemPrompt` 只需要描述翻译要求。Provider 会追加目标语言、`source` / `comment` 输入约定、
占位符规则和固定 JSON 输出约束。

推荐说明：

- 产品领域和目标读者；
- UI 文案的语气、长度与大小写习惯；
- 必须保留的品牌名、代码、URL 和占位符；
- 固定术语及其目标语言写法；
- 如何利用 `comment` 消除歧义。

不要在自定义提示词中重复定义返回 JSON 的字段。完整示例见
[AI 翻译](/ai-i18n/guide/advanced/ai-translation.md#如何编写-systemprompt)。



---
url: https://bosens-china.github.io/ai-i18n/api/openai/interfaces/lang-smith-options.md
---

# LangSmithOptions

从 `@ai-i18n/openai` 导入：

```ts
import type { LangSmithOptions } from '@ai-i18n/openai';
```

## 定义

```ts
interface LangSmithOptions {
  apiKey: string;
  project?: string;
  endpoint?: string;
  workspaceId?: string;
}
```

## 字段

| 字段            | 类型       | 必填 | 默认值            | 约束 | 作用                 |
| ------------- | -------- | -- | -------------- | -- | ------------------ |
| `apiKey`      | `string` | 是  | 无              | 非空 | LangSmith API key。 |
| `project`     | `string` | 否  | LangSmith 默认项目 | 无  | 写入的项目名。            |
| `endpoint`    | `string` | 否  | LangSmith 默认地址 | 无  | 自托管或代理地址。          |
| `workspaceId` | `string` | 否  | 无              | 无  | 目标 workspace。      |

只有传入 `OpenAIOptions.langSmith` 时，Provider 才会创建 tracing callback。

```ts
openAI({
  baseURL,
  model,
  langSmith: {
    apiKey: process.env.LANGSMITH_API_KEY!,
    project: 'ai-i18n',
  },
});
```



---
url: https://bosens-china.github.io/ai-i18n/demo/vue.md
---

# Vue 3 示例

## Vue 3 集成演示

示例提供两个 Tab：

- **Setup + `lang="ts"`**：新组件的推荐写法。自动导入的 `t()` 同时用于 script 与
  template，`useI18n()` 只读取 `currentLang`、加载状态与切换 action；预声明响应式文案
  使用 `tRef()`。
- **纯 Options API**：不使用 `setup()`。通过 `i18nComputed()` 暴露响应式状态，
  `tComputed()` 创建响应式文案，script 与 template 直接使用自动导入的 `t()`。

两个 Tab 共用同一个 Runtime。任一 Tab 切换语言后，另一个 Tab 的文案、当前语言与加载状态
会同步更新；加载失败也会保留当前语言并展示共享错误状态。


## Vue 3 集成演示



[单独打开 ↗](/ai-i18n/examples/vue/)

配置步骤和组件库 locale 同步见 [Vue 快速上手](/ai-i18n/guide/getting-started/vue.md)。



---
url: https://bosens-china.github.io/ai-i18n/demo/react.md
---

# React 示例

## React 集成演示

基于 `useI18n` Hook 订阅 Runtime 变更，切换语言后组件树即时重渲染。


## React 集成演示



[单独打开 ↗](/ai-i18n/examples/react/)

配置步骤和组件库 locale 同步见 [React 快速上手](/ai-i18n/guide/getting-started/react.md)。



---
url: https://bosens-china.github.io/ai-i18n/demo/vanilla.md
---

# Vanilla JS 示例

## Vanilla JS 集成演示

显式调用 `t()`，通过 `subscribe()` 监听语言切换事件并更新原生 DOM。


## Vanilla JS 集成演示



[单独打开 ↗](/ai-i18n/examples/vanilla/)


---
url: https://bosens-china.github.io/ai-i18n/index.md
---

# ai-i18n

Vite AI 国际化

> 直接编写源文案，自动提取、翻译并生成语言包。

[快速上手](/guide/getting-started/vanilla) | [在线演示](/demo/vue)

## Features

- [**快速上手**](/guide/getting-started/vue): 按 Vanilla、Vue 或 React 完成安装、Vite 配置和第一次 Build。
- [**接入与使用**](/guide/basic/static-analysis/common): 查找文案写法、自动导入、语言加载、生成文件和 Git 规则。
- [**工程质量**](/guide/quality/typescript): 接入 TypeScript 生成声明、ESLint 静态检查和 Vitest 测试。
- [**翻译自动化**](/guide/advanced/ai-translation): 选择应用内 Provider 或外部 Agent 补齐译文，并保留人工审校入口。
- [**排查问题**](/guide/faq/common): 按通用、Vue 和 React 场景定位接入与运行问题。
- [**API 参考**](/api): 按包入口查询公开函数、配置字段、类型与默认行为。