ai-i18n

    生成文件与 Git

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

    i18n/
├── translations/          # 项目自动译文分桶
│   └── <locale>/<0-f>.json
├── overrides/             # 项目人工译文分桶
│   └── <locale>/<0-f>.json
├── extracted/
└── locales/

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

    • translations/：保存 Provider、Agent 或个人缓存补齐的项目自动译文。
    • overrides/：保存人工确认的最终译文。它优先于自动翻译结果。

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

    Git 提交规则

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

    • src/ai-i18n.d.ts，或通过 dts 配置的声明文件；
    • Vue 自动导入模式生成的相邻 .vue.d.ts 声明文件；
    • i18n/translations/**/*.json；
    • i18n/overrides/**/*.json。

    将以下目录加入 .gitignore：

    i18n/extracted/
i18n/locales/
**/i18n/translations/.transaction.json
**/i18n/overrides/.transaction.json
**/i18n/translations/**/*.tmp-*
**/i18n/overrides/**/*.tmp-*
logs/
*.log

    .transaction.json 用于异常中断后恢复完整事务，*.tmp-* 是原子替换期间的同目录 临时文件。它们都不是项目译文，进程异常退出时可能短暂残留，不应提交。不要因此忽略整个 translations/ 或 overrides/ 目录。

    开发期间这些临时文件可能在写入完成后立即消失，无需手工创建或删除。插件忽略内部事务日志与 原子写入临时文件的变更通知。真实译文分片的新增、修改和删除仍会触发同步。异常中断后的恢复 由后续正常存储读取或写入完成。

    如果旧版开发服务器报 ENOENT ... .transaction.json，这是文件变更通知到达后文件已消失的热更新 读取竞态。仅凭这一错误不能判断译文损坏。真实分片在事件排队后消失时，插件仍会同步最新译文状态。

    不要通过补建事务文件或忽略整个译文目录来处理。否则可能影响事务恢复或后续译文更新。

    logs/ 与 *.log 是 OpenAI Provider 的本地日志，可能包含业务文案。使用自定义日志目录时也要 忽略该目录。日志内容与分享前检查见 LLM 日志与排障。

    每个目标语言最多生成 16 个非空分桶，条目按稳定 SHA-256 身份分配。分桶可以随源码提交，也便于在 PR 中审查译文变化；团队成员与 CI 拉取同一份仓库后，可以直接复用已经提交的自动译文和人工译文。

    Important

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

    安装 @ai-i18n/sqlite 并配置 translationMemory.cache: sqlite() 时，个人数据库位于用户目录。 它不提交 Git。缓存命中的候选仍会补写进项目 translations/。因此新机器和 CI 继续使用已经提交的项目 译文。详情见 翻译记忆。

    声明文件的作用和自定义路径见 TypeScript 与生成声明。

    什么时候扫描，什么时候构建

    开发服务器只处理浏览器实际访问过的模块。准备用 Agent 批量补译时，可以让 翻译 Skill 从应用入口扫描。这不需要先运行完整构建。 首次补译、切换分支、修改源码或提取配置后，以及 extracted/ 缺失或过期时，都应刷新扫描。 扫描覆盖可静态到达的本地依赖和懒加载页面。未引用的文件不会进入清单。

    完整 vite build 用于生产接入验证、构建专用页面生成，并默认删除当前入口不再引用的自动译文。 扫描与完整构建都会按所选入口重建清单，并迁移旧的 extracted 文件命名。扫描保留历史译文， 不执行孤立和容量清理。 若要先审查孤立译文，临时设置 cleanup.orphanMessages: false 再运行完整 Build，然后使用 MCP 列表工具审查。

    Vite 开发服务器的翻译校对页面在当前页面模式使用开发环境结果。全部页面和独立页会按需刷新入口可达的 完整清单，无需先构建。修改未访问页面也会更新已打开的完整校对列表。 扫描缓存位于 Vite cacheDir，只用于跳过重复提取，可以删除重建。译文和人工覆盖始终读取项目中的最新文件。

    成功构建默认输出文案总数与各语言的已翻译、未翻译数量，包含人工覆盖。可用 diagnostics.buildSummary: false 关闭；启用性能诊断时会合并输出，见 诊断配置。

    Monorepo 中的目录归属

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

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

    web 引用 packages/ui 的本地 ESM 源码时，完整构建会把 UI 文案纳入 apps/web/i18n。 共享源码包通常无需重复注册 ai-i18n，也无需单独创建 i18n 目录。 只有拥有独立 Vite 构建的共享源码包，才需要单独接入并创建目录。

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

    缺译时会发生什么

    目标语言缺少译文时，页面会显示源码文案。你可以配置 AI 翻译，也可以按 补齐和确认译文手动处理。 需要在发布前保证译文齐全时，可设置 failOnMissingTranslations: true，让缺译的 Build 失败。

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

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

    处理合并冲突

    JSON 中出现重复键

    读取生成的 JSON 时，插件会检查同一对象内的重复键，包括转义后相同的键：

    • 值相同：正常读取；下一次该文件的正常同步或写入会合并成一个键。自动译文和人工覆盖 即使没有业务值变化，也会在写入事务中完成清理。仅查询不会为去重改写文件。
    • 值不同：停止当前操作，保留冲突文件，并提示文件路径和两处行列位置。请确认最终值后 只保留一个键，再重试；不会默认采用最后一个值，也不会通过构建强行覆盖。

    这套检查默认生效，无需配置。开发服务器、入口扫描和构建在正常同步时处理各自写入的文件。 校对保存、MCP 写入和 Provider 保存译文共用存储层，不必为了清理额外执行完整构建。 对象字段顺序和字符串转义不影响相同值判断；数组顺序保留，数字表示不同会保守地按冲突处理。 已有事务日志仍按原有机制恢复。不同文件、不同语境中的相同文案不属于重复键。

    Git 合并

    不同哈希桶使用不同文件，Git 通常可以直接合并。同一桶内的不同条目以完整哈希键区分。解决冲突时 保留双方不同键的条目。若双方修改了同一个完整哈希键，应由负责人确认最终措辞，不要按文件时间自动 选择。解决冲突后运行一次构建，再检查页面效果。

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