前端国际化【免费下载链接】react-i18nextInternationalization for react done right. Using the i18next i18n ecosystem.项目地址https://gitcode.com/gh_mirrors/re/react-i18next点击查看免费下载导读本文以仓库中的 razzle-ssr 示例 为蓝本完整讲解如何在Vite SSR React Express技术栈中集成 react-i18next实现服务端语言检测、服务端直出翻译、客户端零闪烁水合hydration以及通过i18next-http-middleware保证每个请求拥有独立的 i18next 实例彻底规避多用户并发下的语言串号竞态问题最后还会演示 i18next 的saveMissing功能如何在服务端落地。读完本文你将能独立搭建一个生产可用的 React SSR 国际化骨架。一、示例项目概览从 Razzle 迁移到 Vite SSR示例目录example/razzle-ssr/早期基于 Razzle 脚手架现已演进为Vite SSR官方 SSR 方案 Express 服务端。核心依赖在 package.json 中expressHTTP 服务器与中间件宿主i18nextreact-i18next国际化核心与 React 绑定i18next-fs-backend服务端从文件系统加载翻译资源i18next-http-backend浏览器端通过 HTTP 加载翻译资源i18next-http-middleware服务端中间件负责按请求创建 i18next 实例、语言检测、缺失键上报i18next-browser-languagedetector浏览器端语言检测vitevitejs/plugin-react开发服务器与构建工具react-router-dom客户端/静态路由目录结构的关键部分example/razzle-ssr/ ├── server.js # Express 入口中间件、SSR 渲染、生产静态服务 ├── vite.config.js # Vite React 插件配置 ├── index.html # HTML 模板含 !--app-head-- 与 !--app-html-- 占位 └── src/ ├── i18n.js # 浏览器端 i18next 初始化 ├── entry-server.jsx # 服务端渲染入口 ├── entry-client.jsx # 客户端水合入口useSSR ├── App.jsx / Home.jsx # 业务组件 └── locales/ # 翻译资源en/translations.json、de/translations.json二、快速启动与运行验证2.1 开发模式npm install npm startnpm start实际执行node server.js见 package.json开发模式下server.js会通过 Vite 的createServer({ server: { middlewareMode: true }, appType: custom })注入中间件实现热更新 SSR。启动后访问地址效果http://localhost:3000自动检测语言根据浏览器 Accept-Languagehttp://localhost:3000/?lngde强制德语http://localhost:3000/?lngen强制英语语言切换由i18next-http-middleware的LanguageDetector驱动?lng查询参数是其中一种检测来源。2.2 生产构建与运行npm run build npm run start:prodbuild脚本做了两件事见 package.jsonbuild: vite build --outDir dist/client vite build --ssr src/entry-server.jsx --outDir dist/server, start:prod: NODE_ENVproduction node server.js第一条命令把客户端资源构建到dist/client第二条命令把src/entry-server.jsx以 SSR 模式构建到dist/server生产模式下server.js读取dist/client/index.html作为模板动态import(./dist/server/entry-server.js)执行服务端渲染并用express.static托管dist/client。三、服务端核心每请求独立 i18next 实例杜绝竞态3.1 为什么必须每请求一个实例react-i18next 的 i18next 单例是可变全局状态。在 SSR 场景中若所有请求共享同一个实例用户 A 设置语言为德语、用户 B 设置为英语时后者的changeLanguage会覆盖前者正在渲染的翻译状态造成串号race condition。这正是 README 中特别强调的Usesi18next-http-middlewareon the serverside to assert that every request gets his own instance of i18nextno race condition conflicts when user b overrides set language in i18next singleton of user a!!!3.2 中间件装配流程server.js 中先初始化基础 i18next 实例挂载i18next-fs-backend与LanguageDetectorawait i18n .use(Backend) .use(i18nextMiddleware.LanguageDetector) .init({ debug: false, preload: [en, de], ns: [translations], defaultNS: translations, backend: { loadPath: ${appSrc}/locales/{{lng}}/{{ns}}.json, addPath: ${appSrc}/locales/{{lng}}/{{ns}}.missing.json, }, });preload: [en, de]服务端启动时预加载两种语言避免首个请求等待文件 IOloadPath正常翻译资源的加载路径模板addPathsaveMissing缺失键的写入路径详见第六节随后将中间件挂载到 Expressapp .disable(x-powered-by) .use(i18nextMiddleware.handle(i18n)) .post(/locales/:lng/:ns, express.json(), i18nextMiddleware.missingKeyHandler(i18n)) .use(/locales, express.static(${appSrc}/locales));i18nextMiddleware.handle(i18n)会在每个请求到来时基于i18n克隆出一个独立实例挂到req.i18n上源码中该克隆实例带有isClone标记并按请求参数?lng、cookie、header 等检测语言。这样并行请求之间互不干扰。3.3 服务端渲染入口使用 req.i18nentry-server.jsx 通过I18nextProvider把req.i18n请求级实例注入组件树export function render(req) { const html renderToString( I18nextProvider i18n{req.i18n} Suspense fallback{divStill loading i18n.../div} StaticRouter location{req.originalUrl} App / /StaticRouter /Suspense /I18nextProvider, ); // First preferred language const initialLanguage req.i18n.languages[0]; // Fill initialI18nStore with only the necessary namespaces. const initialI18nStore {}; const usedNamespaces req.i18n.reportNamespaces.getUsedNamespaces(); req.i18n.languages.forEach((language) { initialI18nStore[language] {}; usedNamespaces.forEach((namespace) { initialI18nStore[language][namespace] req.i18n.services.resourceStore.data[language][namespace]; }); }); return { html, initialI18nStore, initialLanguage }; }这段代码体现了 SSR 国际化的三个关键动作渲染用renderToString输出完整 HTML期间组件内的useTranslation/Trans会消费req.i18n的翻译资源收集语言req.i18n.languages[0]取请求最终确定的首选语言导出翻译快照reportNamespaces.getUsedNamespaces()只收集本次渲染实际用到的命名空间并遍历req.i18n.languages含回退语言链把对应资源打包进initialI18nStore—— 只传必要数据不把全部资源冗余下发。关于reportNamespaces它由 react-i18next 在渲染过程中记录被使用的命名空间是“按需序列化翻译”的基础避免客户端拿到一整包无用资源。四、将翻译下传客户端useSSR 与零闪烁水合4.1 服务端注入脚本server.js拿到render(req)的返回值后把initialI18nStore与initialLanguage序列化进headconst head script window.initialI18nStore ${JSON.stringify(initialI18nStore).replace(//g, \\u003c)}; window.initialLanguage ${JSON.stringify(initialLanguage)}; /script; res .status(200) .set({ Content-Type: text/html }) .send(template.replace(!--app-head--, head).replace(!--app-html--, html));注意.replace(//g, \\u003c)把转义为\u003c防止翻译内容中的特殊字符破坏内联脚本或引发 XSS。index.html模板中预留了!--app-head--注入脚本与!--app-html--注入渲染后的 HTML两个占位符。4.2 客户端水合useSSR 接管entry-client.jsx 在hydrateRoot前调用 react-i18next 的useSSRconst BaseApp () { useSSR(window.initialI18nStore, window.initialLanguage); return ( Suspense fallback{divStill loading i18n.../div} BrowserRouter App / /BrowserRouter /Suspense ); }; hydrateRoot(document.getElementById(root), BaseApp /);这正是 README 强调的Translations are passed down to client on initial serverside render - no reload of translations, no flickering查看 src/useSSR.js 的实现可以发现几个重要细节克隆实例跳过if (i18n.options?.isClone) return;—— 当useSSR意外运行在服务端例如在服务端组件里被调用或面对中间件克隆实例时直接跳过避免在服务端错误地写入初始 store一次性注入资源if (initialI18nStore !i18n.initializedStoreOnce)保证资源只注入一次且会把 store 里出现的命名空间合并进i18n.options.ns这样后续语言切换时会按需加载全部命名空间一次性切换语言if (initialLanguage !i18n.initializedLanguageOnce)用changeLanguage(initialLanguage)让客户端与 SSR 输出语言保持一致且只执行一次。正是因为客户端直接使用服务端下传的完整资源快照水合时不需要再发 HTTP 请求加载翻译因此**不会出现“先英文闪烁、再跳成德语”**的体验问题也不会产生重复请求。五、浏览器端 i18next 配置要点src/i18n.js 是浏览器端初始化文件几个值得关注的配置const options { fallbackLng: en, supportedLngs: [en, de], load: languageOnly, // we only provide en, de - no region specific locals like en-US, de-DE ns: [translations], defaultNS: translations, saveMissing: true, debug: true, backend: { addPath: /locales/{{lng}}/{{ns}}, // missing keys are posted here (see server.js) }, interpolation: { escapeValue: false, // not needed for react!! formatSeparator: ,, format: (value, format, lng) { if (format uppercase) return value.toUpperCase(); return value; }, }, }; // for browser use http backend to load translations and browser lng detector if (typeof window ! undefined) { i18n.use(Backend).use(initReactI18next).use(LanguageDetector); } if (!i18n.isInitialized) { i18n.init(options); }逐项解读load: languageOnly只加载en/de这类语言级资源不做en-US、de-DE之类的地区拆分与本示例的目录结构一致backend.addPath指向服务端POST /locales/:lng/:ns用于saveMissing上报见下节escapeValue: falseReact 本身会对输出做转义交给 react-i18next 后无需二次转义这是 react-i18next 场景下的标准推荐配置format函数演示了自定义格式化t(key, { val, format: uppercase })可触发大写格式化formatSeparator: ,用于分隔多个格式名条件加载仅当typeof window ! undefined时才挂载http-backend与浏览器语言检测器保证该文件在 SSR 构建Node 环境中不被意外引用浏览器专用模块。组件侧Home.jsx同时演示了两种 APIconst [t] useTranslation(translations); // ... h2{t(message.welcome)}/h2 // ... Trans i18nKeyguideline To get started, edit codesrc/App.js/code or codesrc/Home.js/code and save to reload. /Trans对应的英文资源en/translations.json{ message: { welcome: Welcome to Razzle with i18n }, guideline: To get started, edit 1src/App.js/1 or 3src/Home.js/3 and save to reload. }Trans组件会把 JSX 子节点按位置映射为1、3等占位标签实现富文本翻译保留内联元素样式德语资源de/translations.json同样使用占位符语法。useTranslation则用于纯文本插值场景。六、saveMissing缺失键自动收集与落盘README 指出completely allows saveMissing feature of i18next - added content will be pushed to server (POST /locales/:lng/:ns) and stored insrc/locales/{{lng}}/{{ns}}.missing.json整个链路由三处协同完成客户端开启开关src/i18n.js 中saveMissing: true并把backend.addPath指向/locales/{{lng}}/{{ns}}。当页面出现某个语言缺失的翻译键时i18next-http-backend会自动向该地址发起POST服务端接收server.js 中app.post(/locales/:lng/:ns, express.json(), i18nextMiddleware.missingKeyHandler(i18n))接收 JSON 请求体交给中间件内置处理器落盘中间件根据初始化时配置的backend.addPath: ${appSrc}/locales/{{lng}}/{{ns}}.missing.json把缺失键追加写入对应语言的*.missing.json文件例如src/locales/de/translations.missing.json供翻译人员后续补全后合并进正式资源。这一机制让翻译流程形成闭环先跑应用收集缺失键 → 翻译人员按 missing 文件补齐 → 合并回 translations.json无需人工逐条登记缺词。同时server.js还通过.use(/locales, express.static(${appSrc}/locales))把src/locales目录静态托管让浏览器端i18next-http-backend能从/locales/en/translations.json这类 URL 直接拉取正式翻译资源——Express 同时扮演了“翻译文件静态服务器”和“缺失键接收器”的双重角色。七、整体请求链路小结一次典型 SSR 请求的完整流程浏览器请求http://localhost:3000/?lngdeExpress 的i18nextMiddleware.handle(i18n)为请求克隆独立 i18next 实例解析?lngde确定语言entry-server.jsx用I18nextProvider注入req.i18nrenderToString直出德语 HTML同时收集已用命名空间的翻译快照server.js把initialI18nStore/initialLanguage注入head返回完整 HTML浏览器端entry-client.jsx先调useSSR注入服务端下传的翻译快照再hydrateRoot水合组件即刻渲染正确语言无二次请求、无闪烁若切换语言如通过i18n.changeLanguage(en)浏览器端经i18next-http-backend从/locales静态服务加载对应资源若遇到缺失键且saveMissing: true自动POST到/locales/:lng/:ns由missingKeyHandler写入*.missing.json。八、可继续深入的仓库线索服务端渲染与翻译快照导出的完整实现server.js、entry-server.jsx客户端水合与零闪烁机制entry-client.jsx、useSSR.js浏览器端 i18next 配置与 saveMissing 开关src/i18n.jsTrans富文本翻译与useTranslation用法Home.jsx构建脚本与依赖版本package.json中英文翻译资源示例en/translations.json、de/translations.json如果你需要更贴近生产的选择仓库还提供了其他 SSR/服务端相关示例如 ReactNativeProject、react 等可对照阅读而本示例的 Vite SSR Express 方案尤其适合作为**同构应用Isomorphic App**的国际化工地起点。赞分享前端国际化【免费下载链接】react-i18nextInternationalization for react done right. Using the i18next i18n ecosystem.项目地址https://gitcode.com/gh_mirrors/re/react-i18next点击查看免费下载相关推荐react-i18next 实战指南基于 i18next 生态的 React 国际化完整方案react i18next 实战指南基于 i18next 生态的 React 国际化完整方案 导读 react i18next 是 i18next 国际化生态前端国际化BentoPDF 国际化i18n实战指南基于 i18next 的 22 语言翻译体系与静态预渲染架构BentoPDF 国际化i18n实战指南基于 i18next 的 22 语言翻译体系与静态预渲染架构 导读 本文以开源仓库 bentopdf https:前端Nitro 与 SolidJS 服务端渲染SSR实战基于 Vite 的完整接入指南Nitro 与 SolidJS 服务端渲染SSR实战基于 Vite 的完整接入指南 本指南以仓库中的 vite ssr solid 官方示例为核心完整演后端Web框架SSR上一篇简单快速B站缓存视频转换工具m4s-converter完整使用指南下一篇FanControl风扇识别故障解决方案从驱动拦截到硬件适配的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
