企业官网建设流程全解析

做前端时间长了，几乎早晚会撞上“给项目加多语言”的需求。如果只是硬编码几个文案，随便搞个配置文件也能凑合，但一旦涉及语言切换、动态文案、日期格式、懒加载资源这些事，自己造轮子就是给自己挖坑。我现在的项目里用的方案是i18next配合react-i18next，这套组合在 React 生态里算是事实标准了。这篇文章就把我这几年踩过的坑、沉淀下来的配置方式和项目里真正在用的写法完整理一遍，给准备做国际化的朋友一个可以直接照抄的参考。

1. 国际化需求分析与方案选型

1.1 先搞清楚要解决什么问题

国际化（i18n，internationalization 的缩写）表面上是“把界面文案翻译成多语言”，但真正做起来会发现，问题远不止翻译本身。我总结下来，一套合格的国际化方案至少要能解决四件事：

第一，静态文案的抽取和替换。这是最基础的，页面上所有的按钮、标题、提示语都要从写死的字符串变成可查表的 key。第二，动态内容的处理。比如“你有 3 条新消息”这种句子，英文和中文的语序、复数规则完全不一样，不能靠硬拼字符串。第三，语言切换时整个界面要即时响应，不能刷新页面才能生效。第四，资源文件的组织和加载要清晰，不能项目越做越大，语言包变成一堆乱麻。

除了这四点，实际项目里还会有日期时间格式、货币符号、数字千分位这些“区域文化”层面的差异。比如同是显示日期，中文习惯“2024年5月1日”，英文习惯“May 1, 2024”，这属于本地化（localization）的范畴，跟翻译是两码事。所以选型的时候，我优先看的就是这个库对这些能力的覆盖程度。

1.2 为什么是 i18next + react-i18next

React 生态里做国际化，有react-intl（底层是 FormatJS）、react-i18next、还有各种轻量自研方案。我最后选了i18next + react-i18next，核心原因有三个。

第一是i18next本身是一个框架无关的完整国际化引擎，react-i18next只是它针对 React 封装的一层接口。这意味着如果以后前端框架换了，或者同一个仓库里要做非 React 模块（比如工具函数、图表库配置）的国际化，核心逻辑还能复用，不用推倒重来。

第二是i18next的功能覆盖面够广。语言检测、资源懒加载、嵌套翻译、复数、上下文、插值、格式化这套体系已经发展了很多年，社区里各种插件齐全，遇到需求不用自己发明轮子。

第三是它的生态成熟度。GitHub 的 star 数、npm 下载量、文档完整度、Stack Overflow 上的问答量都已经到了一个让人放心的水平。做技术选型，最怕选一个作者不维护、需求没人接盘的库，i18next在这点上风险很低。

当然，react-intl也很好，尤其是在消息语法上更规范，但对项目的侵入性、灵活度跟i18next的“约定优于配置”比起来，我还是觉得i18next上手更顺。尤其是公司项目经常要对接产品、运营反复改文案，i18next的 key 体系和资源文件结构更直观，非技术人员也看得懂。

1.3 在动手之前先规划语言资源结构

我见过很多项目国际化做到一半改崩，问题往往不是库用得不对，而是语言资源的结构一开始没规划好。资源文件的组织方式，基本决定了一个项目的国际化能走多远。

我把语言资源拆成“命名空间（namespace）”维度。简单项目可能一个translation就够，但稍微大一点的项目，我会按业务模块拆：common（公共文案）、header（导航）、dashboard（工作台）、settings（设置）等等。这样每个文件职责单一，多人协作冲突少，按需加载也方便。

语言方面，我建议用语言代码当 key，比如en-US、zh-CN，别偷懒只写en、zh。因为同一个英文，英国和美国在某些单词拼写、日期格式上是有差异的，现在不区分，以后想区分就得做一次全量改动，成本很高。另一个细节是中文资源文件里的 key 用什么命名。我习惯用带语义的英文路径，比如common.confirm、dashboard.welcomeMessage，而不是直接用页面文本当 key。用英文文本当 key 当时写起来快，但产品让你把英文文案换个表达方式时，你就得全局改引用，特别痛苦。

2. 环境搭建与基础配置

2.1 初始化 i18n 实例的正确姿势

安装依赖很简单，两个包：i18next和react-i18next。如果要做语言检测，再加一个i18next-browser-languagedetector。

npm install i18next react-i18next i18next-browser-languagedetector

接着在项目里单独建一个配置文件，不要直接把初始化代码写在入口文件里。我通常建src/i18n/index.ts，把整个 i18n 实例的初始化逻辑收敛在这里。

import i18n from 'i18next'; import { initReactI18next } from 'react-i18next'; import LanguageDetector from 'i18next-browser-languagedetector'; import { enUS } from './locales/en-US'; import { zhCN } from './locales/zh-CN'; i18n .use(LanguageDetector) .use(initReactI18next) .init({ resources: { 'en-US': { translation: enUS }, 'zh-CN': { translation: zhCN }, }, fallbackLng: 'en-US', interpolation: { escapeValue: false, }, detection: { order: ['localStorage', 'navigator'], caches: ['localStorage'], }, }); export default i18n;

这里有几个关键配置我单独说下。

fallbackLng是兜底语言，当某个 key 在当前语言下找不到时，会去这个语言里找，再找不到才显示 key 本身。这个配置必须设，否则缺失翻译会直接展示 key 字符串，线上用户看到一串英文点路径，体验很糟。

interpolation.escapeValue: false这个配置是 react-i18next 官方特别强调的，因为 React 自身已经处理了 XSS 转义，i18next 就不需要再做一遍转义，避免转义之后内容被当成字符串展示。

detection.order是语言检测插件的优先级。我习惯优先读 localStorage，没有再用浏览器语言。这样用户上次手动选择的语言能被记住，而不是每次刷新都会被浏览器语言覆盖。

2.2 翻译函数 t 的两种使用方式

初始化之后，组件里怎么用才是重点。react-i18next提供了两种主要用法：hook 和 HOC。现在项目基本都用函数组件，所以首选useTranslationhook。

import { useTranslation } from 'react-i18next'; function Header() { const { t, i18n } = useTranslation(); return ( <header> <span>{t('common.welcome')}</span> <span>{t('common.login')}</span> </header> ); }

t函数是翻译的核心，第一个参数是 key，第二个参数是可选配置对象。i18n实例则暴露了语言切换、当前语言读取等能力。

另一种用法是Trans组件，这个组件专门用来处理“一段文案里夹杂着嵌套组件”的情况。比如“我已阅读并同意《用户协议》”，这句话里“《用户协议》”需要是一个可点击的链接，普通字符串硬拼根本拼不出来。用Trans组件，资源文件里写精确到组件的嵌套结构：

{ "agreement": "我已阅读并同意 <link>《用户协议》</link>" }

import { Trans } from 'react-i18next'; function Agreement() { return ( <p> <Trans i18nKey="agreement" components={{ link: <a href="/terms" target="_blank" /> }} /> </p> ); }

Trans在业务里非常实用，凡是文案里要嵌入超链接、加粗、颜色标注、React 组件的场景，都应该用它而不是把富文本当 HTML 字符串去拼。

2.3 语言资源文件的组织方式

我的资源文件层数是这样的：最外层是语言目录，第二层是命名空间文件，再往下一层才是具体文案 key。如果你的项目配置了vite或webpack，还可以配合i18next-resources-for-ts这类工具，或者直接用 JSON 文件配合import导入。

// src/i18n/locales/zh-CN.ts export const zhCN = { common: { welcome: '欢迎回来', login: '登录', confirm: '确认', cancel: '取消', }, dashboard: { title: '工作台', messageCount_one: '你有 {{count}} 条新消息', messageCount_other: '你有 {{count}} 条新消息', }, };

这里建议不要用纯 JSON 文件存语言资源，虽然能用，但类型收不到，后面接入 TypeScript 的时候会比较痛苦。用ts文件，配合typeof可以实现 key 的类型约束，这个在第五章细说。

3. 核心功能落地：从静态文本到动态内容

3.1 插值与变量替换

静态文本替换只是国际化的入门，真正体现 i18next 价值的是动态内容。先看插值，当你需要把用户的姓名拼进欢迎语时，用{{变量名}}占位就行。

const { t } = useTranslation(); t('common.welcomeUser', { name: user.name });

资源文件里：

{ "common": { "welcomeUser": "欢迎回来，{{name}}" } }

插值配置里还可以传格式化函数，比如对变量做大小写转换、百分比格式化。不过我现在基本不在t里传格式化函数，而是用 i18next 的format回调统一处理，后面会提到。

插值有个坑，如果你的文案里需要输出字面量的{{，需要写成{{-或者用转义，否则会被当成插值解析。这个不太常见，但真遇到了会懵一阵。

3.2 复数形式与上下文

复数处理是中式思维最容易忽略的点。中文里“1 条消息”和“3 条消息”都在“条”前面换个数字，但英文里message要变成messages，而且有些语言（比如俄语、阿拉伯语）的复数规则非常复杂，不是简单的单复数区分。

i18next 的解决办法是后缀_one、_other，默认支持很多语言的复数规则。

{ "dashboard": { "messageCount_one": "You have {{count}} new message", "messageCount_other": "You have {{count}} new messages" } }

t('dashboard.messageCount', { count: newMessages.length });

i18next 会自动根据count的值匹配带正确后缀的 key。中文里不需要区分单复数，通常只定义一个 key 就行，但如果你定义了一整套_one、_other也没关系，中文会默认落到某个规则上，不会报错。

上下文（context）功能解决的是“同一个概念在不同场景下用词不同”的问题。比如“预约”这个词，做名词和做动词在英语里分别是appointment和book，i18next 允许你给同一个基础 key 加不同的上下文后缀：

{ "booking": { "order_context_noun": "Appointment", "order_context_verb": "Book now" } }

t('booking.order', { context: 'noun' }); t('booking.order', { context: 'verb' });

这个效果是 key 在查找时会自动拼接为booking.order_context_noun，找不到就回退到booking.order。实际项目中我用到上下文的场景主要是性别称谓、名词动词冲突、正式/非正式语气切换。

3.3 日期、数字与货币的本地化格式

i18next 核心库不处理日期和数字的本地化，需要配合IntlAPI 来做。我在项目里用i18next的format配置统一处理。

i18n.init({ interpolation: { format: (value, format, lng) => { if (format === 'date') { return new Intl.DateTimeFormat(lng).format(value); } if (format === 'number') { return new Intl.NumberFormat(lng).format(value); } if (format === 'currency') { return new Intl.NumberFormat(lng, { style: 'currency', currency: 'USD', }).format(value); } return value; }, }, });

t('common.createdAt', { date: new Date(), format: 'date' });

资源文件里：

{ "common": { "createdAt": "创建时间：{{date, date}}" } }

{{date, date}}这种写法，逗号后面是格式名称，i18next 会把这个标识传给format回调。用Intl的好处是浏览器已经内置了几乎全世界的语言规则，你不用自己维护月份名、星期名、数字千分位规则，而且同一套代码换语言后输出是自动适配的。

这里补充一个细节：Intl的DateTimeFormat接收的lng参数要注意格式。如果你配置的是en-US，直接传en-US就能正确识别；如果配置了zh-CN，传zh-CN和zh都行，但个别老浏览器对不标准的语言代码会抛异常，所以建议统一使用xxx-XX格式。

3.4 命名空间与模块化资源管理

当项目变大，把所有文案塞一个translation命名空间里，文件会膨胀到几千行，根本没法维护。我建议从第一天就用命名空间拆分。

初始化时通过ns声明默认加载的命名空间，业务组件里可以指定使用哪个命名空间：

// 指定使用 common 命名空间 const { t } = useTranslation('common'); // 也可以传入数组，使用多个 const { t } = useTranslation(['common', 'dashboard']);

资源文件组织成：

{ "common": { "confirm": "确认", "cancel": "取消" }, "dashboard": { "title": "工作台" } }

懒加载部分等会儿单独讲。先说一个容易犯的毛病：命名空间拆得太细也不行。我之前在一个项目里按“页面级”拆了二十多个命名空间，结果一个菜单组件要同时引三四个命名空间，代码非常啰嗦，还容易出 key 冲突。合理的粒度应该按“业务域”拆，一个业务域内的页面共享一个命名空间，公共部分放common。

4. 语言检测与自动切换的完整链路

4.1 语言检测的原理与配置

语言检测这事，i18next-browser-languagedetector基本把能想的路径都覆盖了：本地存储、navigator.language、URL 的?lng=参数、cookie、还有localStorage以外的各种存储。它的工作方式是按order数组配置的优先级依次取，找到第一个可用的就用。

我配置的order: ['localStorage', 'navigator']意味着先看 localStorage 里有没有用户手动设置过的语言，没有再取浏览器语言。caches: ['localStorage']表示检测成功后把结果缓存到 localStorage。

为什么要把缓存开起来？想象一个场景：用户打开英文版页面，点了几下登录，刷新浏览器后发现变成中文了，那用户一定会觉得产品有毛病。缓存就是为了让语言选择“有记忆”。这个体验细节很小，但对国际化产品来说直接影响留存。

4.2 手动切换语言与持久化

语言切换非常简单，调用实例的changeLanguage方法就行。

import { useTranslation } from 'react-i18next'; function LanguageSwitcher() { const { i18n } = useTranslation(); const currentLang = i18n.language; const handleChange = (lang: string) => { i18n.changeLanguage(lang); }; return ( <div> <button onClick={() => handleChange('zh-CN')} disabled={currentLang === 'zh-CN'}> 中文 </button> <button onClick={() => handleChange('en-US')} disabled={currentLang === 'en-US'}> English </button> </div> ); }

配合语言检测插件的caches配置，changeLanguage调用后会自动把语言写入 localStorage，不需要手动处理。我自己有个习惯，切换语言时还会顺手改一下<html>的lang属性，这样对屏幕阅读器友好，也方便浏览器翻译插件识别页面语言。

useEffect(() => { document.documentElement.lang = i18n.resolvedLanguage || i18n.language; }, [i18n.language, i18n.resolvedLanguage]);

注意我用了resolvedLanguage而不是language。因为fallbackLng的存在，i18n.language可能返回的不是当前实际使用的语言，而是回退之后的结果。resolvedLanguage会告诉你真正被解析到的语言，也就是资源文件加载成功的那个。

4.3 动态加载语言包（懒加载）

中小项目把全部语言包打进主包问题不大，但一个大型后台管理系统，中文 + 英文两份完整的资源文件合计可能几十 KB，如果还包含日文、韩文、法文等多语言，体积会膨胀得很厉害。更科学的做法是：只在用户切换语言时加载对应语言包。

借助i18next-http-backend，资源文件可以独立成 JSON 文件，运行时通过 HTTP 请求按需拉取。

npm install i18next-http-backend

import i18n from 'i18next'; import { initReactI18next } from 'react-i18next'; import HttpApi from 'i18next-http-backend'; import LanguageDetector from 'i18next-browser-languagedetector'; i18n .use(HttpApi) .use(LanguageDetector) .use(initReactI18next) .init({ fallbackLng: 'en-US', ns: ['common', 'dashboard'], defaultNS: 'common', backend: { loadPath: '/locales/{{lng}}/{{ns}}.json', }, interpolation: { escapeValue: false, }, });

这样初始化时不需要在代码里引入任何语言资源，第一次渲染会按照loadPath的规则去请求/locales/zh-CN/common.json这类文件。文件放法就是在public/locales目录下按语言、命名空间建目录。

实际用下来，懒加载最大的收益不只是首屏体积变小，而是团队协作更顺畅。新加入一个语言，只需要新增一份 JSON 目录，不需要改任何初始化代码。要注意的是，HTTP 请求是异步的，在语言包加载完成前组件可能会短暂渲染空白或 key 本身。react-i18next提供了useSuspense配合Suspense处理加载状态，默认是开启的。

import { Suspense } from 'react'; function App() { return ( <Suspense fallback={<Loading />}> <MainContent /> </Suspense> ); }

如果不想用 Suspense，初始化时设置react: { useSuspense: false }，然后自己判断i18n.isInitialized或ready状态来渲染加载壳。

5. 进阶场景与工程化实践

5.1 让 TypeScript 给翻译 key 上上锁

用 TypeScript 的最大红利，就是让翻译 key 的错误在编译期暴露，而不是等用户反馈“页面上怎么显示了一个 xxx.common.welcome”。react-i18next对 TS 的支持很成熟，做法是在类型声明文件里声明模块类型。

// src/types/i18next.d.ts import 'i18next'; import { enUS } from '../i18n/locales/en-US'; declare module 'i18next' { interface CustomTypeOptions { defaultNS: 'common'; resources: { common: typeof enUS; dashboard: typeof enUS; }; } }

这里用en-US的资源文件作为类型基准，因为英文资源文件通常是最全的。配置好之后，t('common.welcome')这种调用就有了完整的类型提示，key 拼错一概编译不过。配合编辑器的自动补全，根本不用记 key 名。

资源文件多的时候还能用i18next-resources-for-ts这个工具自动生成类型，我用的方式是直接手写resources类型，因为项目里资源文件不算太多，手写也能接受。如果你用了 JSON 文件资源，又想获得类型提示，可以用resolveJsonModule配合脚本把 JSON 转成 TS 类型再 import。

5.2 与后端接口返回文案的联动

产品里有种常见需求：部分文案来自后端接口，比如运营配置的活动标题、服务端返回的错误提示。这里我踩过一次坑，一度直接把后端返回的文案当成翻译 key 用t()去查，结果自然是啥也查不到。

正确做法是区分处理。后端返回的若是纯展示文案，直接渲染就好，不需要走 i18next；若后端返回的是固定的错误码，前端通过错误码映射到翻译 key 进行处理。

const errorMessages: Record<string, string> = { USER_NOT_FOUND: 'errors.userNotFound', INVALID_PASSWORD: 'errors.invalidPassword', }; // 组件里 const { t } = useTranslation('errors'); const messageKey = errorMessages[error.code] ?? 'errors.unknownError'; setErrorMessage(t(messageKey));

这个思路特别适合错误提示的国际化。后端只负责传稳定的错误码，前端根据当前语言渲染对应文案，既不用后端关心多语言，也不会因为后端的文案风格不稳定导致 UI 飘忽不定。至于运营配置的动态内容，建议后端直接返回已经按用户语言偏好准备好的文案，前端不做二次处理。

5.3 与路由、状态管理、UI 组件库的适配

国际化不是孤立的，它要跟项目里的其他基础设施配合。先说路由：比较规范的做法是把当前语言放进 URL，比如/en/dashboard、/zh-CN/dashboard。这样语言可以分享给链接，用户把链接发给别人时，对方看到的是同一语言。实现方式是在路由切换时把语言作为前缀，配合i18n.changeLanguage。这个方案不是必须的，如果产品只要求语言选择记住即可，localStorage 方案更简单。

再说 UI 组件库，很多组件库内置了自己的国际化资源，比如日期选择器的面板文案、分页器的上一页下一页。这些不会自动跟随 i18next 的语言切换，需要手动同步。比如在 Ant Design 里：

import zhCN from 'antd/locale/zh_CN'; import enUS from 'antd/locale/en_US'; import { ConfigProvider } from 'antd'; const antdLocale = i18n.language.startsWith('zh') ? zhCN : enUS; <ConfigProvider locale={antdLocale}> <App /> </ConfigProvider>

这种适配本身不复杂，但容易漏。我建议在初始化 i18next 后，通过监听languageChanged事件统一同步第三方库的语言配置，而不是在组件里手动一个个处理。

i18n.on('languageChanged', (lng) => { // 更新 UI 组件库的 locale // 更新 dayjs 的 locale // 更新 axios 请求头里的语言标识 });

5.4 与服务端渲染（SSR/Next.js）的配合

如果项目用了 Next.js 这类 SSR 框架，国际化要额外注意双端一致性。react-i18next在 SSR 下的经典搭配是i18next-resources-for-ssr或者直接使用next-i18next这样的封装库。

基础的思路是：服务端渲染时初始化一个独立的 i18n 实例，把当前请求的语言传给实例，然后在渲染完成后把语言资源序列化到客户端，避免客户端再发一次请求下载语言包。这个过程容易出错的地方是实例的复用，千万不能用一个全局单例处理所有请求，因为每个请求的语言可能不同。每次请求都需要createInstance新建一个实例，或者用cloneInstance复制。

我自己在 Next.js 里更推荐直接用社区维护的next-i18next，它把服务端语言检测、资源下发、客户端水合这层细节都封装好了，没必要自己重新实现一遍。

6. 常见问题与排查技巧实录

6.1 语言切换后页面不更新

这是一个高频问题，表现是调用changeLanguage后，部分组件没有重新渲染。大部分情况下，是因为组件里使用了普通的string拼接，而不是走t()函数。

比如：

const message = '当前语言：' + i18n.language;

这种写法当然不会响应语言变化。还有另一种情况：某些第三方组件库用了自己的文案，没有接入 i18next。排查思路就一句话：所有要跟随语言变化的内容，都必须由t()函数或useTranslation触发渲染。

有一个隐藏的坑是，useTranslation的重新渲染依赖组件挂载时传入的命名空间，如果你在一个组件里用了t，但用的是组件库内部缓存的 t 函数副本，也可能不刷新。碰到这种，优先检查是不是 hook 没有在正确的组件里调用。

6.2 个别 key 一直显示 key 字符串而不是译文

翻译 key 显示成原文，那是查找失败了。排查路径我一般按三步走。

先查资源文件本身，确认 JSON 或 TS 文件没有语法错误，引号、逗号是否匹配。我在一个老项目里就遇到过 JSON 某个字符串里含了一个未转义的反斜杠，导致整个文件解析失败，UI 上所有文案全部显示 key，排查了半小时。再查 key 路径是否正确，特别是嵌套层级。common.confirm到底对应的是{ common: { confirm: '确认' } }还是{ 'common.confirm': '确认' }，这两种写法完全不一样。最后查命名空间，如果资源进了common命名空间，但调用时写的是t('dashboard.something')，然后资源里没有dashboard这个命名空间，就会掉到fallbackLng。用i18n.getResourceBundle(lng, ns)可以快速检查当前已加载的资源里到底有没有这个 key。

要是排查完这些都没问题，再看一眼是不是缓存惹的祸。我这边是后端同学更新了语言包，但 CDN 缓存了旧文件，浏览器拿到的还是老资源，这种一般等缓存过期或手动清缓存就能验证。

6.3 语言切换时组件闪烁或直接白屏

这个问题的根源几乎都是懒加载模式下，切换语言是需要重新发请求拿资源的。在资源到达之前，如果组件已经把被切换掉的旧文案销毁了，就会出现白屏或闪烁。

处理办法有三种。最推荐的是用Suspense包住业务组件树，切换语言期间展示兜底的 loading，资源就绪后再渲染真正的 UI。其次是在changeLanguage调用前，先用i18n.hasResourceBundle判断一下这个语言包是否已经加载过，没加载过就先调用i18n.loadNamespaces预加载。最后是给小语言的资源文件配置合理的缓存策略，让第二次切换不需要再重新下载。

我自己的项目里，因为对切换速度要求比较高，所以用了本地资源引用的方式，没有走 HTTP 懒加载。权衡点是这样：公司主要面向中英两种语言，合计体积不大，首屏直接带上也能接受；如果以后要加的语言多了，再切换回 HTTP 懒加载也简单，初始化配置里改一个 backend 而已。

6.4 一些提升开发体验的边角料

有几个不常用但特别好使的小技巧，顺带分享一下。

在开发环境想快速看到某个 key 的全部译文，浏览器控制台执行i18n.getResourceBundle(i18n.language, 'common')就能打印出整个命名空间。排查翻译问题比一个个点页面快得多。

如果你发现页面上某个文案一直显示翻译前的英文，但资源文件里明明改了，十有八九是本地开发语言包被缓存了。在初始化配置里加一个loadPath的版本参数，比如/locales/{{lng}}/{{ns}}.json?v=1.2.3，就能强制刷新缓存。

另外i18next有个debug: true配置项，初始化时打开它，控制台会输出所有 key 的查找路径和结果。定位 key 找不到的问题基本就是一把梭，定位完记得在生产环境关掉。

最后再说一点我个人的体会。国际化这件事，技术本身不难，难点在规范意识。用react-i18next只是第一步，真正重要的是从项目第一天起就养成“所有文案都走 key”的习惯，后端错误码统一、组件库语言联动、资源文件模块化这些事情，越早定好规则，后面越省心。我自己前前后后维护过几个国际化的中大型系统，一个很深的感受是：那些国际化做到一半乱掉的项目，不是败在工具上，而是败在团队成员随手硬编码、key 命名随心所欲这些看似小的问题上。所以如果你是刚开始给项目接入国际化，别光装完库就跑，先把资源组织方式和 key 命名约定定下来，团队里所有人写码时严格遵守，这才是国际化项目长期好维护的真正关键。