前端国际化方案

国际化（Internationalization，简称 i18n）是前端工程化中不可或缺的一环。随着业务覆盖多语言市场，如何高效、可维护地管理翻译文本、处理多语言路由和 SEO，成为前端架构的重要课题。

i18n 核心策略

Key-Value 翻译模式

最常见的 i18n 模式。每个文本对应一个唯一的 key，各语言维护一份 key-value 映射文件：

json

{
  "nav.home": "首页",
  "nav.about": "关于我们",
  "common.submit": "提交"
}

json

{
  "nav.home": "Home",
  "nav.about": "About Us",
  "common.submit": "Submit"
}

ICU Message 格式

适用于需要复数规则、性别匹配、插值等复杂场景的翻译格式：

{count, plural,
  =0 {暂无商品}
  one {# 个商品}
  other {# 个商品}
}

ICU Message 提供了更强大的表达能力，尤其适合阿拉伯语、俄语等拥有复杂复数形态的语言。

流行库对比

特性	react-intl	vue-i18n	i18next
框架绑定	React	Vue	框架无关
ICU Message	✅ 原生支持	✅ 插件支持	✅ 插件支持
延迟加载	✅	✅	✅
TypeScript	✅ 良好	✅ 良好	✅ 优秀
嵌套翻译	✅	✅	✅
社区生态	丰富	丰富	极丰富
包体积	~30KB	~10KB	~35KB

选型建议

React 项目：优先选择 react-intl（FormatJS 生态），或 i18next + react-i18next
Vue 项目：优先选择 vue-i18n（官方方案），或 i18next + vue-i18next
多框架/跨平台：i18next 是框架无关方案，支持 React/Vue/Angular/Svelte 等

翻译文件管理

目录结构

src/
  locales/
    zh-CN/
      common.json
      nav.json
      dashboard.json
      settings.json
    en/
      common.json
      nav.json
      dashboard.json
      settings.json
    ja/
      common.json
      nav.json
      dashboard.json
      settings.json
    index.ts          # 导出所有语言包

自动化工具链

工具	用途
i18next-scanner	从源码扫描翻译 key，自动生成翻译模板
formatjs/cli	react-intl 配套 CLI，支持提取、编译
Crowdin / Lokalise	云端翻译管理平台，支持可视化翻译
Lint i18n	检查未使用的 key 或缺失的翻译

推荐工作流：

开发阶段使用 key 标记文本
CI 阶段通过 CLI 提取新 key 并合并到翻译文件
推送至翻译平台，由翻译团队完成多语言翻译
构建时打包对应语言包

多语言路由

常见的多语言路由设计方案：

方式	URL 示例	说明
子路径	`/zh-CN/about`, `/en/about`	SEO 友好，实现简单
子域名	`zh.example.com`, `en.example.com`	可独立部署，适合大流量站点
Cookie/Header	Cookie: `lang=zh-CN`	不改变 URL，SEO 不友好

推荐使用子路径方案，兼顾 SEO 和可维护性。Vue Router / React Router 可通过全局导航守卫或路由前缀实现。

多语言 SEO

<html lang="zh-CN">：正确声明页面语言

hreflang 标签：告诉搜索引擎各语言版本的对应关系

html

<link rel="alternate" hreflang="zh-CN" href="https://example.com/zh-CN/about" />
<link rel="alternate" hreflang="en" href="https://example.com/en/about" />
<link rel="alternate" hreflang="x-default" href="https://example.com/" />

sitemap 多语言：在 sitemap.xml 中标注每种语言的 URL

运行时 vs 构建时国际化

维度	运行时国际化	构建时国际化
加载方式	运行时动态加载 JSON	构建时生成多份静态页面
切换速度	即时切换（无刷新）	需整页刷新
SEO	较差（内容由 JS 渲染）	优秀（SSG 生成多语言页面）
适用场景	SPA / 管理后台	内容型网站 / 公开页面

实际项目中通常采用混合策略：公开页面使用构建时国际化（SSG 多语言），管理后台使用运行时国际化。

实践要点

尽早引入：项目启动时即引入 i18n 方案，避免后期大批量替换
命名规范：维护清晰的 key 命名规范，如 模块.子模块.描述
回退机制：翻译缺失时回退到默认语言
缓存策略：语言包可缓存至 localStorage，减少重复加载
RTL 支持：阿拉伯语等从右到左语言需要配合 CSS 逻辑属性

前端国际化方案 ​

i18n 核心策略 ​

Key-Value 翻译模式 ​

ICU Message 格式 ​

流行库对比 ​

选型建议 ​

翻译文件管理 ​

目录结构 ​

自动化工具链 ​

多语言路由 ​

多语言 SEO ​

运行时 vs 构建时国际化 ​

实践要点 ​