graph TD
    A[业务调用层<br/>useSubtitle(lang)] --> B[调度层 LanguageScheduler]
    B --> C{状态机判断}
    C -->|未加载| D[加载层 Loader<br/>fetch/import()]
    C -->|已缓存| E[缓存层 Cache<br/>IndexedDB/Memory]
    C -->|加载中| F[任务去重 Promise]
    D --> G[解析/校验]
    G --> E
    E --> H[实例化 i18n 资源]
    H --> A

enum LangPackStatus { Idle, Loading, Ready, Error, Stale }

// 切换语言核心逻辑伪代码
async function switchLang(targetLang: string): Promise<LangPack> {
  const pack = scheduler.getPack(targetLang);
  
  // 1. 就绪态直接返回，触发 LRU 更新
  if (pack.status === LangPackStatus.Ready) return pack.activate();

  // 2. 加载中复用 Promise，避免重复请求
  if (pack.status === LangPackStatus.Loading) return pack.promise;

  // 3. 过期/错误态触发重新加载
  pack.status = LangPackStatus.Loading;
  pack.promise = loader.load(targetLang).then(res => {
    pack.data = res; pack.status = LangPackStatus.Ready;
    cache.set(targetLang, res); // 写入双级缓存
    return pack;
  }).catch(err => { pack.status = LangPackStatus.Error; throw err; });

  return pack.promise;
}

// 目录结构示例
locales/
  ├── core/           # 核心 UI 词条（按钮、提示、设置）~30KB
  ├── asr/            # 语音识别专有术语、实体词表 ~80KB
  ├── meeting/        # 会议流程、角色、动作词条 ~50KB
  └── domain/         // 垂直领域扩展包（医疗/法律/金融）按需下载

class LangPackCache {
  private memoryCache = new Map<string, { data: LangPack; lastAccess: number }>();
  private readonly MAX_MEMORY_ENTRIES = 3; // 仅保留当前 + 最近 2 个

  activate(lang: string) {
    const entry = this.memoryCache.get(lang);
    if (entry) entry.lastAccess = Date.now();
    this.evict();
  }

  private evict() {
    if (this.memoryCache.size <= this.MAX_MEMORY_ENTRIES) return;
    // 找到最久未访问且非当前激活语言
    const sorted = [...this.memoryCache.entries()].sort((a, b) => a[1].lastAccess - b[1].lastAccess);
    for (const [lang, entry] of sorted) {
      if (lang !== this.currentActiveLang) {
        this.memoryCache.delete(lang); // 释放 JS 堆引用
        break;
      }
    }
  }
}

// scripts/gen-i18n-types.ts (构建钩子)
import { writeFileSync } from 'fs';
import { globSync } from 'glob';

const files = globSync('dist/locales/**/*.json');
const manifest: Record<string, { version: string; hash: string; keys: string[] }> = {};
const typeDefs: string[] = ['declare module "virtual:i18n-manifest" {', '  export const manifest: typeof import("./manifest.json");', '}'];

files.forEach(file => {
  const lang = file.match(/locales/(.+).json$/)?.[1];
  if (!lang) return;
  const content = JSON.parse(readFileSync(file, 'utf-8'));
  const keys = Object.keys(flatten(content)); // 扁平化键路径
  manifest[lang] = { version: pkg.version, hash: hash(content), keys };
  
  // 生成每个语言包的精确类型
  typeDefs.push(`declare module "locales/${lang}" {`);
  typeDefs.push(`  export default ${JSON.stringify(content, null, 2)} as const;`);
  typeDefs.push(`}`);
});

writeFileSync('dist/locales/manifest.json', JSON.stringify(manifest));
writeFileSync('src/types/i18n-generated.d.ts', typeDefs.join('n'));

// src/i18n/loader.ts
import type { LangPack } from './types';

// 利用模块增强实现类型推导
declare module 'virtual:i18n-manifest' {
  export const manifest: Record<string, { version: string; hash: string; keys: string[] }>;
}

export async function loadLangPack<T extends LangPack>(lang: string): Promise<T> {
  // 1. 类型层面约束 lang 必须是 manifest 中存在的键
  const mod = await import(/* @vite-ignore */ `locales/${lang}.json`) as { default: T };
  
  // 2. 运行时 Schema 校验（防止 CDN 劫持/构建产物损坏）
  const expectedHash = (await import('virtual:i18n-manifest')).manifest[lang]?.hash;
  const actualHash = hash(mod.default);
  if (expectedHash && actualHash !== expectedHash) {
    throw new Error(`[i18n] Hash mismatch for ${lang}: expected ${expectedHash}, got ${actualHash}`);
  }
  
  return mod.default;
}

// 业务侧调用：享受完整键路径提示
const pack = await loadLangPack('zh-CN');
pack.meeting.toolbar.mute; // ✅ 类型安全，重构自动重命名

// sw-config.mjs (Workbox 配置)
import { defineConfig } from 'workbox-build';

export default defineConfig({
  globDirectory: 'dist',
  globPatterns: [
    'locales/core/**/*.json',      // 核心包：CacheFirst，长期驻留
    'locales/asr/**/*.json',       // 专业包：StaleWhileRevalidate，后台更新
    'locales/domain/**/*.json',    // 垂直域包：NetworkFirst，按需拉取
  ],
  maximumFileSizeToCacheInBytes: 5 * 1024 * 1024, // 单文件 5MB 上限
  runtimeCaching: [
    {
      urlPattern: //locales/.*.json$/,
      handler: 'StaleWhileRevalidate',
      options: {
        cacheName: 'i18n-packs-v2',
        expiration: { maxEntries: 50, maxAgeSeconds: 30 * 24 * 3600 }, // 30天
        plugins: [
          // 关键：版本变更时自动清理旧版缓存
          {
            cacheWillUpdate: async ({ response, request }) => {
              const url = new URL(request.url);
              const manifest = await caches.match('/locales/manifest.json');
              if (manifest) {
                const data = await manifest.json();
                const lang = url.pathname.split('/').pop()?.replace('.json', '');
                if (data[lang] && response.headers.get('ETag') !== data[lang].hash) {
                  return null; // 拒绝缓存不匹配版本，强制走网络
                }
              }
              return response;
            }
          }
        ]
      }
    }
  ]
});

// sw-broadcast.ts (Service Worker 内)
self.addEventListener('message', event => {
  if (event.data.type === 'LANG_PACK_UPDATED') {
    // 广播给所有受控客户端
    self.clients.matchAll().then(clients => {
      clients.forEach(client => client.postMessage({
        type: 'I18N_RELOAD_REQUIRED',
        lang: event.data.lang,
        version: event.data.version
      }));
    });
  }
});

// 主线程监听
navigator.serviceWorker.addEventListener('message', event => {
  if (event.data.type === 'I18N_RELOAD_REQUIRED') {
    i18nScheduler.invalidateCache(event.data.lang); // 标记失效
    if (i18nScheduler.currentLang === event.data.lang) {
      i18nScheduler.reloadCurrentLang(); // 当前语言热更新
    }
  }
});

sequenceDiagram
    participant ASR as ASR 引擎
    participant Render as 字幕渲染器
    participant I18n as 语言包调度器
    
    ASR->>Render: 推送源语言 Token 流 (srcTokens)
    Render->>Render: 立即渲染源语言字幕 (降级显示)
    
    par 并行加载目标语言包
        Render->>I18n: requestLangPack(targetLang)
        I18n-->>Render: Promise<LangPack> (可中途 resolve)
    end
    
    loop 每帧渲染循环
        alt 语言包就绪
            Render->>Render: 翻译缓冲区 srcTokens -> 替换显示
        else 语言包未就绪
            Render->>Render: 继续显示源语言 + "翻译中..." 标记
        end
    end

// packages/i18n-core/src/scheduler.ts
export interface IStorageAdapter {
  get(key: string): Promise<Uint8Array | null>;
  set(key: string, data: Uint8Array): Promise<void>;
  delete(key: string): Promise<void>;
  keys(): Promise<string[]>;
}

export interface ILoaderAdapter {
  load(lang: string): Promise<Uint8Array>; // 返回原始二进制
}

export class LanguageScheduler {
  constructor(
    private storage: IStorageAdapter,
    private loader: ILoaderAdapter,
    private options: SchedulerOptions
  ) {}
  
  // 核心逻辑：状态机、LRU、预加载、增量合并... 纯逻辑，可单测
  async loadLang(lang: string): Promise<LangPack> { /* ... */ }
}

// loader.ts 安全加载流程
async function secureLoad(lang: string) {
  const { url, hash } = manifest[lang];
  const response = await fetch(url, { integrity: `sha384-${hash}` }); // 浏览器原生 SRI 校验
  if (!response.ok) throw new Error('SRI validation failed');
  return response.arrayBuffer();
}
// 注意：动态 import() 不支持 integrity 属性，生产环境核心包建议改用 fetch + eval/Function 或 WASM 解析，或配合 Trusted Types 政策。

# .github/workflows/i18n-security.yml
- name: Scan i18n packs
  run: |
    npx i18n-security-scanner 
      --input dist/locales 
      --rules xss,sql-injection,sensitive-data,size-anomaly 
      --fail-on high