Vite 国际化与多语言构建：按语言分包、懒加载与回退策略

反模式：import zh from './zh.json'; import en from './en.json' ...
正解：  动态 import(`./locales/${lang}.json`)

src/locales/
  zh-CN/
    common.json      → 通用按钮、提示
    home.json        → 首页专属
    errors.json      → 错误码文案
  en-US/
    common.json
    home.json
    errors.json

- 用「语义」而不是「原文」做键：common.save 而不是 common.保存
- 层级不超过三层，过深难维护
- 复数、插值等特殊结构用统一的约定（如 _one / _other）
- 键一旦发布就不要改名，改名等于所有语言都要改

{
  "save": "保存",
  "greeting": "你好，{{name}}",
  "cart_items_one": "购物车有 {{count}} 件商品",
  "cart_items_other": "购物车有 {{count}} 件商品"
}

// src/i18n.ts
import i18n from 'i18next'
import { initReactI18next } from 'react-i18next'

i18n.use(initReactI18next).init({
  lng: localStorage.getItem('lang') ?? 'zh-CN',
  fallbackLng: 'en-US',
  ns: ['common'],
  defaultNS: 'common',
  interpolation: { escapeValue: false },
})

export default i18n

const modules = import.meta.glob('./locales/*/*.json')

async function loadNamespace(lng: string, ns: string) {
  const loader = modules[`./locales/${lng}/${ns}.json`]
  const mod = await loader()
  return mod.default
}

zh-CN.home.title 缺失 → 回退 en-US.home.title
整份 zh-CN 未加载     → 回退 en-US

dist/assets/
  zh-CN-common-a1b2c3.js
  en-US-common-d4e5f6.js
  首页 chunk（不包含任何语言文案）

new Intl.NumberFormat('zh-CN', { style: 'currency', currency: 'CNY' }).format(1234.5)
// ¥1,234.50

new Intl.DateTimeFormat('en-US', { dateStyle: 'long' }).format(new Date())
// October 2, 2026

const pr = new Intl.PluralRules('en-US')
const form = pr.select(3)   // 'other'
// 用 form 去选 cart_items_one / cart_items_other

{
  "items": "{count, plural, =0 {没有商品} one {# 件商品} other {# 件商品}}"
}

async function switchLang(lng: string) {
  await i18n.changeLanguage(lng)
  localStorage.setItem('lang', lng)
  // 若用路径前缀，则同步更新 URL 而不 reload
  history.replaceState(null, '', `/${lng}${location.pathname.replace(/^\/[a-z-]+/, '')}`)
}

export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        chunkFileNames: (chunk) =>
          chunk.name.includes('locale')
            ? 'assets/locales/[name]-[hash].js'
            : 'assets/[name]-[hash].js',
      },
    },
  },
})

// 用户悬停语言切换按钮时预取
function prefetchLang(lng: string) {
  const link = document.createElement('link')
  link.rel = 'prefetch'
  link.href = `/assets/locales/${lng}-common.js`
  document.head.appendChild(link)
}

import zhCommon from './locales/zh-CN/common.json'

i18n.init({
  lng: 'zh-CN',
  resources: { 'zh-CN': { common: zhCommon } },
})

<link rel="preload" href="/assets/locales/zh-CN-common.js" as="script" crossorigin />

- 单语言单命名空间 ≤ 30KB（gzip 后 ≤ 10KB）
- 首屏内联文案 ≤ 15KB
- 语言 chunk 总数控制在 20 个以内

1. 开发只写默认语言的键与文案
2. 提交流程中抽取新增键，生成待翻译清单
3. 翻译平台回填其他语言
4. CI 校验：所有语言键集合是否一致、有无缺失

// 校验各语言键集合一致性
const base = Object.keys(zhCN)
for (const lang of others) {
  const diff = base.filter((k) => !(k in lang))
  if (diff.length) throw new Error(`${lang} 缺失键: ${diff}`)
}

□ 文案按语言 + 命名空间组织
□ 语言文件走 import.meta.glob 动态加载
□ 回退链：同语言其他命名空间 → 默认语言
□ 格式化统一用 Intl，复数用 PluralRules
□ URL 用路径前缀，切换不刷新
□ 默认语言内联，其余懒加载
□ CI 校验各语言键集合一致
□ 监控语言 chunk 体积