前端国际化（i18n）体系设计与工程化落地

睡不着先生
18 阅读3分钟

🌍 前端国际化（i18n）体系设计与工程化落地

✈️ 当一个前端项目开始支持多语言时，问题就不再是“翻译几行文案”那么简单。 国际化（i18n）考验的是：架构设计能力、工程化能力和长期维护能力。

在这篇文章中，咱们不讲“Hello World”，而是讲真正能在项目里落地的 i18n 方案。

🎯 为什么前端国际化一定要提前设计？

很多项目的国际化，都是这样开始的：

“老板说下个月要支持英文版，我们先用 if/else 顶一下。”

然后很快就会出现：

  • 文案散落在代码各处，无法统一管理
  • 新增语言成本极高
  • 翻译人员无法参与，只能靠开发
  • 改一行中文，所有语言一起崩
  • 多语言切换导致页面闪烁、状态丢失

👉 问题的根源只有一个：i18n 没有工程化。

🧩 一、前端国际化的核心设计目标

一个成熟的 i18n 体系，至少要满足：

  1. 文案与业务逻辑彻底解耦
  2. 支持动态语言切换
  3. 支持多人协作（开发 / 产品 / 翻译）
  4. 支持规模化扩展（10+ 语言）
  5. 对性能影响可控

🧱 二、国际化的基础结构设计

1️⃣ 文案统一抽离（这是底线）

❌ 错误示例：

if (lang === 'en') {
  title = 'User List';
} else {
  title = '用户列表';
}

✅ 正确做法：Key-Value 语义化文案

title: t('user.list.title')

语言文件示例：

// zh-CN.json
{
  "user.list.title": "用户列表"
}

// en-US.json
{
  "user.list.title": "User List"
}

2️⃣ Key 命名规范（非常重要）

推荐规则：

模块.页面.含义

示例：

  • login.form.username
  • login.form.password
  • user.list.empty
  • order.detail.status.paid

✅ 好处：

  • 语义清晰
  • 避免 Key 冲突
  • 方便批量维护和查找

🛠️ 三、Vue / React 中的 i18n 实现思路

Vue（vue-i18n 思路）

const i18n = createI18n({
  locale: 'zh-CN',
  messages: {
    'zh-CN': zhCN,
    'en-US': enUS
  }
});

使用：

<h1>{{ $t('user.list.title') }}</h1>

React（react-i18next 思路）

const { t } = useTranslation();

<h1>{t('user.list.title')}</h1>

🔁 四、语言切换的正确姿势

1️⃣ 语言状态存储

推荐优先级：

  1. 用户显式选择（localStorage / cookie）
  2. 浏览器语言（navigator.language）
  3. 默认语言
const lang =
  localStorage.getItem('lang') ||
  navigator.language ||
  'zh-CN';

2️⃣ 切换语言不刷新页面

i18n.global.locale.value = 'en-US';

⚠️ 注意：

  • 不要强制刷新页面
  • 不要丢失当前路由和状态

📦 五、规模化项目的 i18n 工程化方案

1️⃣ 按模块拆分语言文件

locales/
├─ zh-CN/
│  ├─ login.json
│  ├─ user.json
├─ en-US/
│  ├─ login.json
│  ├─ user.json

动态合并：

const messages = {
  'zh-CN': {
    ...loginZh,
    ...userZh
  }
};

2️⃣ 懒加载语言包（性能关键）

async function loadLocale(lang) {
  const messages = await import(`./locales/${lang}.json`);
  i18n.setLocaleMessage(lang, messages.default);
}

✅ 避免一次性加载所有语言。

3️⃣ 文案校验与缺失检测

建议在 CI 中做：

  • Key 是否重复
  • 是否存在未翻译 Key
  • 是否存在废弃 Key

否则迟早会变成“语言文件垃圾场”。

🌐 六、国际化不仅是文案

真正的 i18n 还包括：

📅 时间与日期格式

new Intl.DateTimeFormat('en-US').format(new Date());

💰 数字与货币

new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD'
}).format(1000);

🧭 方向性（RTL）

  • 阿拉伯语 / 希伯来语
  • CSS 要支持 dir="rtl"

⚠️ 七、常见踩坑总结

坑后果
Key 命名随意后期无法维护
文案写死在组件无法扩展
一次加载全部语言性能灾难
翻译人员直接改代码风险极高
没有 Key 校验文案混乱

✅ 总结

一个合格的前端 i18n 体系应该是：

  • 🧱 文案完全解耦
  • 📦 支持模块化与懒加载
  • 🔁 支持无刷新切换
  • 🌍 覆盖语言、日期、货币、方向
  • 🛠️ 可维护、可扩展、可协作

国际化不是“翻译问题”，而是工程问题。

avatar
文章
阅读
粉丝