翻译校对#

ai-i18n 在 Vite 开发服务器业务页面内提供翻译校对插件。你可以比较原文、自动译文与人工译文，并直接修正 不合适的措辞。保存后，业务页面会使用新的译文。

先在 Vite 配置中显式注册 Review 插件：

import { aiI18n } from '@ai-i18n/vite';
import { aiI18nReview } from '@ai-i18n/vite/review';

export default defineConfig({
  plugins: [aiI18n({ sourceLang: 'zh-CN', locales }), aiI18nReview()],
});

aiI18n() 本身不会开启 Review。aiI18nReview() 必须与一个 aiI18n() 注册在同一份 Vite 配置中， 且只能注册一次。不注册时，开发服务器页面没有校对入口。

页面图标和控制台提示可以分别关闭：

aiI18nReview({
  launcher: false,
  printUrl: false,
});

launcher: false 隐藏页面入口；printUrl: false 隐藏控制台提示。两者都不会关闭独立校对页。 完全不需要开发校对时，请从 Vite plugins 中移除 aiI18nReview()。

#打开页面内校对

1. 运行 vite dev。
2. 打开需要检查的业务页面。
3. 点击页面右下角的翻译校对图标，选择目标语言并开始检查。

工作台会贴在业务页面底边，让你在校对时继续查看页面上下文。拖动面板上边缘可以调整高度。 高度只保存在当前浏览器中，不会写入项目配置或翻译文件。

工作台打开后默认显示当前业务页面中实际出现的文案，也可在顶部切换到 全部页面。 它会匹配原文、自动译文和人工译文。带动态值的文案也会按模板占位符匹配。 SPA 路由或页面变化后，列表会自动更新。

当前页面模式使用开发服务器已处理的文案。切换到“全部页面”或打开独立校对页时，会从应用入口补齐 可达页面的文案清单，包括尚未访问的懒加载页面。这不需要先运行完整构建。

已有清单仍有效时复用提取结果。只修改译文会更新翻译状态，不重新提取源码。 保存页面源码后，新增、修改、删除的文案及源码位置会自动同步。未访问页面也一样。 扫描期间显示刷新状态。源码暂时无法解析时保留上次结果，并提示可能过期；修复后自动重试。 保存校对时会复验文案与位置，避免把旧选择应用到已经变更的调用。未保存输入不会被后台刷新覆盖。

完整范围仍是应用入口可静态到达的模块。它不包含未引用文件、运行时才能确定的路由或仅构建生成的页面。 生产接入验证仍需要完整构建。若要先审查孤立译文，请在构建前设置 cleanup.orphanMessages: false；默认构建会直接清理它们。

#打开独立校对页

Vite 开发服务器启动后，控制台会打印完整的 Review 地址。也可以直接打开当前开发服务器下的 /__ai-i18n/。独立页默认直接进入全部已提取文案，并与页面内工作台使用同一份译文。

独立页会显示校对进度、目标语言、筛选和编辑区，适合连续检查完整清单。

独立页没有业务页面上下文，因此不显示 当前页面，也不提供页面取词和滚动定位。 需要按真实页面筛选文案或从元素定位源码时，使用页面内入口。需要集中检查整个提取结果时，使用独立页。

#从页面取词

在嵌入工作台顶部选择“页面取词”，面板会暂时收起。移动到目标元素时会出现带角点的定位框。 点击后，工作台会在页面底部重新打开并定位对应消息。

定位框会短暂保留，让你确认刚才选中了页面中的哪个区域，随后自动消失。

如果相同渲染值对应多个 comment、文件或调用位置，工作台会列出候选。选择正确的候选后，才能修改 当前位置的人工译文。它不会默认选择第一项。

按 Escape 可以退出取词。页面取词只拦截这一次选择点击，不会长期劫持业务事件。

#查看和筛选文案

顶部选项卡为 当前页面、全部页面 与 设置（默认 当前页面）：

• 当前页面：只展示当前业务页面中出现的全部文案，不含搜索与状态筛选。
• 全部页面：可搜索原文、译文、语境或文件，也可按确认状态和文件类型筛选。
• 设置：在深色、浅色和跟随系统之间切换外观；也可以选择跟随浏览器、中文或 English 的界面语言。 两类偏好均保存在当前浏览器中，不会写入项目配置。

只有一个目标语言时，工作台直接使用该语言，不再显示语言选择控件。

“待确认 / 已确认”表示当前语言是否已有人工译文，与自动译文是否缺失无关。同一消息只要有一个 范围的人工译文就会标为“已确认”，不代表所有出现位置都已覆盖。自动译文为 null 表示尚无自动 译文。如果当前位置有有效人工译文，业务页面仍会使用它。两者都没有时才回退原文。

页面会在当前浏览器会话中按文案、目标语言和作用范围保留未保存输入。切换筛选、搜索、语言或作用 范围后再返回，仍可继续原来的编辑。刷新或关闭校对页面前，仍应保存需要保留的修改。

点击属于当前页面的文案时，业务页面会滚动并短暂标记对应元素。需要区分同一文案的多个调用位置时， 使用页面取词。

静态 comment 用于区分文字相同但含义不同的文案。例如，按钮中的“保存”和状态中的“保存”可以 分别设置语境：

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

每条文案都会显示源码位置；点击编辑器图标可以直接跳到该位置。同一文案包含多个调用位置时，先使用页面取词确认要修改的位置。

#选择生效范围

在人工译文输入框上方，通过横向排列的作用范围选项卡选择生效范围：

• 当前位置：只对当前选中的一次调用生效；
• 当前文件：只对当前选中位置所在的来源文件生效；
• 所有文件：对 source 和 comment 相同的全部文案生效。

同一句原文在整个应用中含义一致时，选择所有文件。只有一个文件需要不同译法时选择当前文件。同一 文件内只有某次调用需要不同译法时选择当前位置。源码移动后旧位置不会自动套用到相似文案，需要重新确认。

#确认、修改和继续下一条

没有当前作用范围的人工译文时，输入框会保持空白。自动译文只在上方展示，可按需选择“使用自动 译文”填入。只有输入非空且模板占位符校验通过时，确认按钮才可用。

主按钮根据当前状态说明将要发生的操作：

• 确认译文：输入新的人工译文后保存；
• 保存修改：输入与当前值不同；
• 已保存：当前人工译文没有变化，不会重复提交。

主按钮右侧的“继续 →”会在保存成功后切换到下一条可见文案，并更新业务页面。

保存、修改或撤销“当前位置”的人工译文同样会立即更新业务页面。它不需要手动刷新。 刷新或新开业务页面也会读取最新译文，开启语言按需加载时同样适用。

校对页支持以下快捷键：

• Command/Ctrl + Enter：保存当前人工译文；
• Command/Ctrl + Shift + Enter：保存并继续下一条；
• Alt + A：填入当前自动译文；
• 焦点不在搜索框或人工译文输入框时，按上下方向键切换文案。长列表会自动滚动，保持选中项可见。

需要恢复自动译文时，选择原来的作用范围，再选择“撤销人工译文”。这项操作只删除当前语言、 当前文案和当前范围对应的人工译文，不会删除翻译记忆中的自动译文。

人工译文必须保留原文中的模板占位符。例如，原文包含 {name} 时，译文也必须包含 {name}。 页面会拒绝保存缺少模板占位符的译文。

#与自动翻译的关系

翻译校对不会修改自动译文。人工译文优先于自动译文，且范围越具体优先级越高。自动译文仍不可用时， 页面回退显示原文。

少量关键措辞适合使用校对页面。批量补译与自动化操作更适合使用 AI 翻译或 Agent + MCP。

#使用边界

Review 只在显式注册 aiI18nReview() 后开启，且只在 Vite 开发服务器中可用。 它不会进入构建、Preview 或生产产物。它不需要账号，也不需要额外的 UI 依赖，更不会覆盖业务页面样式。 不需要开发服务器校对时，从 Vite plugins 中移除 aiI18nReview()。

完整补译流程、人工译文格式和提交规则见补齐和确认译文。

#复用历史候选

启用 SQLite 翻译记忆 后，校对编辑区提供“历史候选”。 选择文案和目标语言后按需加载，显示译文、来源项目及人工校对的原文件/位置；同值合并，更多结果可继续加载。 “当前生效”标记包含当前范围继承的人工译文。候选顺序不代表质量，也不会默认预选。

点击“使用此译文”只填入草稿；检查语境、占位符和作用范围，再点击确认或保存。 结果按当前范围写入项目 overrides/，不继承来源项目范围，也不覆盖自动译文。 缓存不可用可重试，正常编辑和保存不受影响。未启用缓存时不显示此区域。