前端国际化（i18n）最佳实践与架构设计指南

react-i18next

React Hooks 友好，支持 SSR 场景下的语言检测。

import React from 'react';
import { useTranslation } from 'react-i18next';

function UserDashboard() {
  const { t, i18n } = useTranslation(['user', 'common']);
  const changeLanguage = (lng) => {
    i18n.changeLanguage(lng);
    document.documentElement.lang = lng;
  };
  return <h1>{t('user:welcomeTitle')}</h1>;
}

SSR 水合报错解决方案：强制统一语言来源（如 Cookie 或 URL 参数）。

架构搭建

文件目录规范

推荐按语言分目录，便于翻译人员协作。

locales/
  zh/
    common.json
    home.json
  en/
    common.json
    home.json

JSON 资源文件编写

使用层级命名空间，避免语义模糊。

{
  "user": {
    "profile": {
      "title": "个人资料",
      "saveSuccess": "保存成功！"
    }
  }
}

动态加载策略

避免首屏包体积过大，按需加载语言包。

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

语言检测策略

组合策略：优先 URL 参数（SEO），其次 Cookie（用户偏好），最后浏览器 Header。

复杂场景处理

复数与性别

不同语言复数规则差异大（如俄语、阿拉伯语）。i18next 内置 CLDR 规则自动处理。

{
  "ru": {
    "key_one": "{{count}} книга",
    "key_few": "{{count}} книги",
    "key_many": "{{count}} книг"
  }
}

日期与货币格式化

使用 Intl API 或库内置格式化，避免手动拼接。

new Intl.NumberFormat('de-DE', { style: 'currency', currency: 'EUR' }).format(1234567.89);

RTL 布局适配

阿拉伯语、希伯来语需从右向左布局。设置 dir="rtl" 并使用 CSS 逻辑属性（margin-inline-start）。

.sidebar {
  float: inline-start;
  margin-inline-end: 20px;
}

PostCSS 插件 postcss-rtlcss 可辅助转换历史代码。

常见问题与优化

兜底策略

配置 fallbackLng 和 parseMissingKeyHandler，防止页面显示 Key 值。

SEO 优化

添加 hreflang 标签告知搜索引擎语言版本。

<link rel="alternate" hreflang="zh" href="https://example.com/zh" />

缓存策略

语言包更新时通过文件名 Hash 或查询参数强制刷新。

自动化与工具

类型安全

为翻译 Key 定义 TypeScript 类型，编译期检查拼写错误。

type Resources = typeof import('./locales/zh.json');
declare module 'react-i18next' {
  interface CustomTypeOptions { resources: Resources; }
}

自动化流程

对接翻译平台 API（如 Lokalise），CI/CD 自动同步键值。

总结

多语言不仅是文字替换，更是文化适配。保持 Key 语义化，提供上下文给翻译人员，并关注颜色、图标等本地化细节。前期良好的架构设计能大幅降低后期维护成本。