前端国际化：从零封装LanguageSelector多语言切换组件

简介这是一份基于React构建的LanguageSelector前端语言选择器项目源码面向前端初学者以及需要快速实现多语言切换界面的Web开发者。项目基于Create React App标准工程搭建提供npm start、npm test、npm run build等常用脚本开发模式支持热更新和代码检查测试模式可交互式运行生产构建会压缩资源并自动生成带哈希值的文件名便于直接部署。资源共15个文件、压缩后约165KB以5个JavaScript逻辑文件、3个JSON配置文件和HTML入口文件为主同时包含图标、页面说明等静态资源整体体积小巧、目录结构规范。通过阅读源码可学习React工程化配置、组件拆分与常用脚本用法也可直接作为语言选择功能的基础模板继续扩展。目前已有173人浏览学习适合边读边改、循序渐进地上手React项目。1. LanguageSelector 是什么一个 HTML 语言选择器该管的四件事很多产品对外发布后第一波海外用户反馈往往不是功能缺陷而是界面语言不对。有人默认收到的是英文有人切了日文但刷新后回到中文还有人明明选了阿拉伯语页面的布局却完全没有跟着翻转。LanguageSelector 就是这样一个基于 HTML/CSS/JavaScript 实现的语言切换组件它要管的不只是点击下拉菜单换文案还包括语言包的加载与缓存、用户选择的持久化、页面 lang 属性和文字方向的同步以及切换后所有动态内容的一致性。适合正在做国际化前端的从业者——新手能照着最小实现跑通流程熟手能直接带走边界处理思路。2. 从零搭一个 LanguageSelectorDOM 结构、事件绑定与最小可用版2.1 为什么用原生 HTML/CSS/JS而不是框架现成组件第一个要回答的问题是有 Element UI、Ant Design 这些现成下拉框为什么还要自己写我的判断标准是语言选择器是全局控件它要同时改 document 的 lang 属性、localStorage、动态插入的 DOM 节点和构建工具、服务端模板都有耦合。用框架组件反而要把业务逻辑塞进组件的生命周期里出问题更难排查。原生实现没有额外依赖一个 JavaScript 文件加一段 CSS 就能嵌入任何页面甚至后端模板引擎也能直接输出这套结构。另外原生实现可以精确控制渲染时机。比如首屏闪白的解法需要在 head 里提前执行 localStorage 读取框架组件做不到这个加载顺序。如果你只是做一个内部管理系统的简单双语言切换框架组件够用但凡涉及多种语言、多区域、需要防御各种浏览器环境原生方式的可控性会好很多。2.2 HTML 结构按钮 菜单而不是 select很多新手会直接用select做语言切换因为表单控件天然支持键盘操作代码量也少。select的问题是选项里的文字也是页面文案的一部分当语言包尚未加载时select会显示空白或者默认文案而且在部分移动端浏览器上select的弹层样式完全由系统决定你没法控制语言名称的展示格式。所以我一般用 button 触发、ul 模拟列表的结构配合 ARIA 属性达到和 select 等价的可访问性。div classlanguage-selector idlanguageSelector button classlanguage-selector__trigger typebutton aria-haspopuplistbox aria-expandedfalse span>(function () { use strict; var LANGS { zh-CN: { selector.currentLang: 简体中文, welcome.title: 欢迎使用, welcome.desc: 这是一个带有语言选择功能的演示页面。 }, en-US: { selector.currentLang: English, welcome.title: Welcome, welcome.desc: This is a demo page with language switching. } }; var DEFAULT_LANG zh-CN; var STORAGE_KEY languageSelector.locale; var selector document.getElementById(languageSelector); var trigger selector.querySelector(.language-selector__trigger); var menu selector.querySelector(.language-selector__menu); var options Array.prototype.slice.call( menu.querySelectorAll([roleoption]) ); function render(locale) { var dict LANGS[locale] || LANGS[DEFAULT_LANG]; document.documentElement.setAttribute(lang, locale); Array.prototype.forEach.call( document.querySelectorAll([data-i18n]), function (node) { var key node.getAttribute(data-i18n); if (dict[key]) { node.textContent dict[key]; } } ); options.forEach(function (option) { var selected option.getAttribute(data-lang) locale; option.setAttribute(aria-selected, selected ? true : false); }); } trigger.addEventListener(click, function () { var expanded trigger.getAttribute(aria-expanded) true; trigger.setAttribute(aria-expanded, String(!expanded)); menu.hidden expanded; }); options.forEach(function (option) { option.addEventListener(click, function () { var locale option.getAttribute(data-lang); if (!LANGS[locale]) { return; } render(locale); try { window.localStorage.setItem(STORAGE_KEY, locale); } catch (e) { // 隐私模式或存储被禁用时忽略 } trigger.setAttribute(aria-expanded, false); menu.hidden true; }); }); render(DEFAULT_LANG); })();render(locale) 里先做document.documentElement.setAttribute(lang, locale)。浏览器会拿这个属性做拼写检查、阅读器朗读发音也是后面 RTL 切换的决策依据。替换文本用的是 textContent 而不是 innerHTML——语言包里的文案来自翻译文件万一翻译里夹带了 HTML 标签innerHTML 等于把 XSS 通道直接开在页面上textContent 最多让你看到一段带标签的纯文本不会执行任何脚本。options 的 NodeList 先通过 Array.prototype.slice.call 转成数组规避旧版浏览器对 NodeList.forEach 不支持的兼容问题。LANGS[locale] || LANGS[DEFAULT_LANG]是兜底逻辑万一 URL 参数或 localStorage 里存了一个已下线的语言代码渲染还是能回退到默认语言。2.4 语言包组织JSON 键值对还是嵌套字典关于语言包的结构常见做法是平铺的键值对。为什么不推荐嵌套字典嵌套结构在读取和合并时都更麻烦读取需要一层层 try/catch合并翻译时要处理深拷贝还要担心某个分支缺失。平铺结构用一个点状命名空间selector.currentLang、welcome.title就能解决问题读取时不管在哪个层级都只查一次。上面演示代码把语言包直接写进了 JS实际工程里通常是独立 JSON 文件按需加载。初始化时先加载默认语言包用户切换到别的语言后再异步加载对应文件避免“加载四种语言、实际只用一种”的浪费function loadLangPack(locale) { if (LANGS[locale]) { return Promise.resolve(LANGS[locale]); } return fetch(assets/i18n/ locale .json) .then(function (response) { if (!response.ok) { throw new Error(语言包加载失败: locale); } return response.json(); }) .then(function (pack) { LANGS[locale] pack; return pack; }); }fetch 返回的是 Promise切换语言时先 loadLangPack 再 render避免点击后出现一小段空白。参数说明assets/i18n/ 是语言包目录命名与>var STORAGE_KEY languageSelector.locale; function getSavedLocale() { var saved null; try { saved window.localStorage.getItem(STORAGE_KEY); } catch (e) { // Safari 隐私模式和部分浏览器禁用存储时会抛异常 } return saved; } function setSavedLocale(locale) { try { window.localStorage.setItem(STORAGE_KEY, locale); } catch (e) { // 写入失败静默处理不影响本次切换 } }有人会问try-catch 是不是想多了我建议你打开 Safari 的隐私浏览模式试一次localStorage.getItem 会直接抛 SecurityError。如果不包 try-catch整个 LanguageSelector 初始化会中断页面上其他脚本也可能跟着挂掉。常见做法是捕获异常后只做内存级的状态保持session 内可用刷新后回退默认语言这属于降级而不是故障。getItem 返回的是字符串如果之前不小心写入了非法的语言代码比如旧版本 bug 写入了一个已经不在支持列表里的 key就需要校验逻辑var SUPPORTED [zh-CN, en-US, ja-JP, de-DE]; function normalizeLocale(locale) { if (SUPPORTED.indexOf(locale) -1) { return locale; } return DEFAULT_LANG; }读取之后过一遍 normalizeLocale 再进入渲染比在 render 里做 fallback 更先发现问题。第 2 章的 render 里也写了LANGS[locale] || LANGS[DEFAULT_LANG]那是渲染层的兜底存储层再校验一次是为了避免把非法值写回 localStorage。3.3 URL 参数覆盖分享链接的语言直达除了本地存储还要支持 URL 参数。典型场景是分享链接用户 A 用德文界面复制给 B 的链接里带着 ?langde-DEB 打开后也应该直接看到德文。URL 参数的优先级应当高于 localStorage因为它是链接显式表达的意图。function resolveLocale() { var params new URLSearchParams(window.location.search); var fromUrl params.get(lang); if (fromUrl SUPPORTED.indexOf(fromUrl) -1) { return fromUrl; } return normalizeLocale(getSavedLocale()); }URLSearchParams 在较老的浏览器里没有如果项目要兼容 IE 或旧版 Edge通常用一个正则解析 search 字符串function getParam(name) { var match new RegExp([?] name ([^]*)).exec(window.location.search); return match ? decodeURIComponent(match[1]) : null; }两种写法效果等价选择哪个取决于目标浏览器的下限。如果已经在用构建工具和 BabelURLSearchParams 省事如果资源是直接放到服务器上的原生 JS正则写法更稳。另一个细节URL 参数一旦进入页面要不要把它写入 localStorage我的习惯是写入。因为用户从分享链接进来后他后续再切换语言应该基于当前 URL 的语言继续走而不是突然跳回旧值。把 URL 参数写入 localStorage 后下次无参数打开页面也能保持分享时的语言。3.4 首屏闪白在 head 里提前恢复 lang 属性闪白的原理很简单浏览器先以默认语言渲染了标题、导航、按钮等外部 JavaScript 文件执行完 localStorage 读取后才改成用户上次选的语言用户肉眼看到的就是“先显示中文再闪成英文”。解决方案是在head里放一段尽量小的 inline script抢在首屏渲染前把 lang 属性改好。head meta charsetUTF-8 title示例页面/title script (function () { var saved null; try { saved localStorage.getItem(languageSelector.locale); } catch (e) {} var lang saved || zh-CN; document.documentElement.setAttribute(lang, lang); })(); /script /head这段脚本只做两件事读 localStorage、设置 html 标签的 lang。它不负责替换文本所以很快基本不会阻塞首屏。真正的文案替换还是等语言包和主 JS 加载完再由主逻辑执行完整 render。如果你想连文案都提前换可以把默认语言包也做成 inline script但那样会让 HTML 体积变大通常不划算。这里的失败模式是如果一段 inline script 抛异常浏览器会直接停止执行后续的 inline script但不影响外部 JS 加载。所以 inline script 里一定要写 try-catch并且代码保持简单这是首屏恢复的最后一道保险。4. 避坑排查LanguageSelector 最常见的五个翻车现场4.1 现象按钮点击没反应控制台报跨域错误现象用编辑器直接双击打开 index.html点了语言选择器的按钮菜单能展开但点击语言选项没有任何反应F12 控制台报 “Cross origin requests are only supported for HTTP”。原因页面是通过 file:// 协议打开的本地 HTML浏览器出于安全策略禁止 fetch 加载本地 JSON 语言包。fetch 请求被拦截后loadLangPack 的 Promise 直接 rejectrender 自然执行不了。这不是代码逻辑错而是加载环境不对。解决本地调试统一用本地静态服务器。在项目根目录跑python3 -m http.server 8000然后访问http://localhost:8000/。如果嫌 Python 麻烦直接装 Live Server 插件点 “Go Live”。从那以后我每次搭建前端 demo 的第一件事就是开本地服务器而不是双击打开 HTML。4.2 现象刷新页面后语言设置丢失现象在设置里切换成英文页面看起来也正常但按 F5 刷新后界面又变成默认中文。原因第一种是初始化入口直接写了 DEFAULT_LANG没有调用 resolveLocalegetSavedLocale 读到的值根本没进渲染流程。第二种是 localStorage 写入失败被 try-catch 吞掉刷新后自然拿不到旧值。解决优先检查初始化入口确认调用的是 resolveLocale() 而不是硬编码默认语言。其次在 Safari 隐私模式下用 console.log 打印 getSavedLocale 的返回值如果为 null 说明存储本身被浏览器禁用。这两步能覆盖 90% 以上的“刷新后设置丢失”问题。4.3 现象切换语言后按钮宽度跳动布局错位现象中文标题短德文标题特别长切换后顶部导航的语言选择器按钮忽宽忽窄把旁边的链接挤到下一行。原因语言选择器的容器没有设置最小宽度或约束最大宽度按钮宽度由文案撑开语言切换后文案长度变化导致重新排布。解决给.language-selector__trigger设置 min-width同时加 white-space: nowrap 防止长文字换行。宽度值按最大语言包的文案长度估算德文和俄文通常需要预留更多空间.language-selector__trigger { min-width: 8em; max-width: 13em; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }如果菜单宽度也跟着跳动给.language-selector__menu设置固定宽度或 min-width用 max-height 限制超长列表滚动。记住多语言界面的布局要按最长语言做设计而不是按默认语言。4.4 现象动态插入的 DOM 节点永远不翻译现象页面里有一段异步加载的评论区切换语言后已加载的评论、按钮文案都变了但新插入的节点还是旧语言。原因render 只遍历了一次document.querySelectorAll([data-i18n])。异步组件插入新节点时没有重新调用 render新节点上的>var observer new MutationObserver(function (mutations) { mutations.forEach(function (mutation) { Array.prototype.forEach.call(mutation.addedNodes, function (node) { if (node.nodeType 1) { translateNode(node); } }); }); }); observer.observe(document.body, { childList: true, subtree: true });注意MutationObserver 是异步回调监听整个 body 会有性能开销不要在大规模页面里滥用。更实际的做法是让所有模块在数据更新后统一走一次 render或者在模块自己的渲染函数里声明依赖语言包的版本号语言包更新时强制重新渲染。4.5 现象浏览器自动翻译和语言选择器打架现象用户用的是 Chrome地址栏自动出现翻译提示一点“翻译成英文”页面上原本被语言包替换的文案又被浏览器翻译了一遍出现“中文界面 英文标签混排”的诡异效果。原因Chrome 的自动翻译是浏览器级别的功能它根据 html lang 属性和用户浏览器语言判断是否弹出翻译条。如果 html lang 是 en-US而浏览器是中文环境Chrome 就会认为页面需要被翻译。语言选择器切换后没有同步更新 lang 属性或者 lang 写的是不标准的 zh 而不是 zh-CN都会触发自动翻译。解决语言选择器每次切换后把document.documentElement.lang设置为标准 BCP 47 代码再在 head 里加一个 meta 标签明确声明不需要自动翻译meta namegoogle contentnotranslate这个标签只对 Google 系浏览器生效Firefox 和 Safari 没有统一的自动翻译机制但设置了不影响其他浏览器。如果产品内部维护了自己的翻译机制还可以配合 Content-Language 响应头让服务端明确声明语言。5. 字体、RTL 与可访问性语言选择器的收尾工程5.1 按语言切换字体栈语言选择器切换的不只是文案还有字体表现。中文用中文字体日文用日文字体英文用西文字体一套写死的 font-family 在切换后会出现奇怪的显示——比如在中文 Windows 上渲染日文字体回退逻辑会先挑系统中文字体日文假名还好汉字可能显示成简体字形。常见做法是按 lang 属性给 body 或根元素挂不同的字体栈html[langzh-CN] body { font-family: -apple-system, PingFang SC, Hiragino Sans GB, Microsoft YaHei, sans-serif; } html[langja-JP] body { font-family: -apple-system, Hiragino Kaku Gothic ProN, Yu Gothic, Meiryo, sans-serif; } html[langen-US] body, html[langde-DE] body { font-family: -apple-system, Segoe UI, Roboto, Helvetica, Arial, sans-serif; }这段 CSS 的触发条件就是 html 标签上的 lang 属性所以第 2 章里“每次渲染都要 setAttribute lang”不是可有可无的规范它直接决定了字体栈是否生效。如果项目里用了 web font还要按语言分开加载比如拉丁字体只加载 Latin 子集、中文字体只加载需要的字符集不然语言包没多大字体文件反而拖垮首屏。5.2 RTL 布局切换阿拉伯语时全局翻转阿拉伯语、希伯来语是从右往左书写的页面里的导航、文字对齐、箭头方向都要跟着翻转。只把文案换成阿拉伯语不够布局也得变。标准做法是在 html 标签上切换 dir 属性function syncDirection(locale) { var RTL_LANGS [ar, he, fa, ur]; var code locale.split(-)[0]; var dir RTL_LANGS.indexOf(code) -1 ? rtl : ltr; document.documentElement.setAttribute(dir, dir); }dir 切换后大多数布局会自动跟着变flex 的主轴方向在 rtl 下会反过来text-align: left/right 的物理方向也会被 dir 重写。真正容易翻车的是那些用了绝对定位或者 left/right 硬编码的组件。比如原本定位在右侧的返回按钮RTL 下应该跑到左侧如果写的是position: absolute; right: 16px它不会跟着变。排查方法很简单切到 RTL 后扫一遍页面里所有 left/right 写死的样式改用 inset-inline-start / inset-inline-end 逻辑属性。逻辑属性是 CSS 里相对容易遗漏的部分但不需要一次性改完。语言选择器自己的菜单在 RTL 下通常需要把菜单位置对齐到主按钮的右侧边缘用逻辑属性写一行 CSS 就能同时满足 LTR 和 RTL.language-selector__menu { inset-inline-end: 0; inset-inline-start: auto; }5.3 可访问性读屏软件不是加分项语言选择器的可访问性重点在三个细节。第一触发按钮的 aria-haspopuplistbox 和 aria-expanded 必须同步更新。读屏用户在点击按钮时需要知道展开的是一个语言列表且当前列表是否展开。第 2 章的 click 里写了 setAttribute(aria-expanded)但 menu.hidden 控制显隐也要保证和 aria-expanded 一致。有一步不一致读屏反馈就是错的。第二每个选项的 aria-selected 必须只在当前语言上为 true。这个逻辑在 render 里做过了但要留意初始化时如果省了 render(DEFAULT_LANG)页面标记和实际显示会不一致。第三焦点管理。菜单展开后焦点应该保持在触发按钮上用户按上下方向键遍历语言选项Esc 键收起菜单。最精简的键盘处理如下menu.addEventListener(keydown, function (e) { if (e.key Escape) { trigger.setAttribute(aria-expanded, false); menu.hidden true; trigger.focus(); } });不要在一个语言选择器上去实现过于复杂的 roving tabindex读屏用户使用 listbox 的标准交互模式即可。键盘操作的目标是“能完成选择”不是“和鼠标操作一样流畅”。5.4 完整目录与接入检查清单到这里一个可以落地的 LanguageSelector 至少包含这几个文件文件作用是否需要index.html页面骨架与语言选择器 DOM必须assets/i18n/zh-CN.json默认语言包必须assets/i18n/en-US.json其他语言包按需assets/css/language-selector.css按钮、菜单、RTL 样式建议assets/js/language-selector.js渲染、持久化、事件绑定必须接入新项目时我一般按清单走一遍确认 html 根元素的 lang 和 dir 有初始值确认 localStorage 和 URL 参数两种入口都能正确判断优先级确认所有动态插入的节点都有翻译入口确认 RTL 语言下菜单位置方向正确最后用隐私模式刷新两次确认无异常。6. 进阶技巧把 LanguageSelector 封装成全局语言事件总线语言选择器做完后最常见的后续需求是不只页面文案要切换日期组件、图表 tooltip、富文本编辑器、甚至服务端下发的错误码提示都要跟着切。如果每个组件各自绑定 LanguageSelector 的点击事件代码会很快变成一团乱麻。我一般把语言变更做成一个事件让所有需要响应语言变化的模块订阅它。function setLocale(locale) { render(locale); saveLocale(locale); syncDirection(locale); window.dispatchEvent(new CustomEvent(language:changed, { detail: { locale: locale, dict: LANGS[locale] } })); }订阅方这样写window.addEventListener(language:changed, function (e) { var locale e.detail.locale; var dict e.detail.dict; document.title dict[meta.title] || DEFAULT_TITLE; if (typeof chartInstance ! undefined) { chartInstance.setLocale(locale); } });这套做法的核心是把“语言状态”和“界面更新”解耦。LanguageSelector 只管改状态、发事件不关心订阅方是谁订阅方也只需要关心语言变了之后自己怎么做。项目中常见的另一个事件是 language:loaderror语言包加载失败时发出去让全局统一弹一次提示而不是每个订阅方各弹各的。注意 CustomEvent 在 IE 和旧版 Edge 上缺失最简降级方案function dispatchLangEvent(detail) { var event; try { event new CustomEvent(language:changed, { detail: detail }); } catch (e) { event document.createEvent(CustomEvent); event.initCustomEvent(language:changed, true, false, detail); } window.dispatchEvent(event); }事件总线的坑主要在重复订阅。模块在单页应用里反复挂载、卸载如果每次挂载都 addEventListener 一次切换语言时回调会被执行两遍甚至更多。经验做法是订阅回调放在模块入口处卸载时 removeEventListener如果做不到用一个订阅计数器兜底回调先检查计数不等于一次就 return。这个技巧我第一次用在某跨平台系统上时坑也被踩了个遍一开始忘了派发 syncDirectionRTL 语言只在文案上变了布局还保持 LTR用户界面看起来像排版事故后来又在几个子模块里重复注册事件切换一次语言触发了十几次图表重绘。从那以后我每次接入新的语言包都强制在 staging 环境走一遍先清空 localStorage 再刷新再删除 URL 参数刷新确认回退路径正常最后再检查事件监听数量。希望帮到你。本文还有配套的精品资源点击获取