语言分包与按需加载

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

配置分包策略

// 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，并希望所有目标语言都在切换时再加载，只需设为 true：

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

省略 loading 或设为 false 保持全语言注册；true 或空对象开启默认分包策略。需要定制提前加载的语言时，传入包含 preload / prefetch 的配置对象。

显示切换中的加载状态

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

所有框架都使用相同的流程：切换时禁用入口，显示 loading 的目标语言；失败时显示 error，并保留当前语言。仅在需要记录、重试或跳转等业务动作时处理 setLang() 的 rejected Promise：

async function switchLanguage(value: string) {
  try {
    await setLang(value);
  } catch {
    // 通用错误状态由界面读取 langLoadState.status。
  }
}

框架	读取状态与更新界面的方式
Vue Composition API	从 `useI18n()` 读取 `isLangLoading`、`langLoadState` 与 `setLang`。
Vue Options API	将 `i18nComputed()` 展开到根 `computed`，并在 `methods` 中调用 `setLang`。
React	从 `useI18n()` 读取相同字段并在组件中渲染。
Vanilla JS	通过 `getLangLoadState()` 读取快照，并使用 `subscribe()` 在页面或视图销毁时取消订阅。

各 API 的签名与完整示例见 Runtime API。

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

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

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

const state = getLangLoadState();

需要持续响应变化时，应像 Vanilla 示例一样配合 subscribe() 重新读取。状态的完整类型与并发语义见 getLangLoadState()。

配置规则

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

完整字段类型与边界见 AiI18nLocaleLoadingOptions。

语言分包与按需加载#

#配置分包策略

#显示切换中的加载状态

#配置规则

语言分包与按需加载

配置分包策略

显示切换中的加载状态

配置规则