最轻量可控的前端国际化方案是用data-i18n标记+JSON语言包+localStorage持久化；需为文本节点设data-i18n键名，属性类如placeholder需用data-i18n-placeholder等对应扩展，语言包按BCP 47规范加载并降级，同步更新document.documentElement.lang及localStorage，避免硬刷页面和覆盖系统偏好。
直接用 data-i18n 标记 + JSON 语言包 + localStorage 持久化，是最轻量、可控、易调试的方案。不依赖框架，也不需要服务端渲染，纯前端就能跑通核心流程。
怎么给 HTML 元素打翻译标记
所有要动态换语言的文本节点，都加 data-i18n 属性，值是统一的键名，比如 "header_title" 或 "btn_submit"：
<h1 data-i18n="header_title">欢迎来到我们的网站</h1> <input type="text" placeholder="" data-i18n-placeholder="search_hint"> <button data-i18n="btn_submit">提交</button>
注意：placeholder、title、alt 这类属性不能靠 textContent 覆盖，得单独处理对应属性名（如 data-i18n-placeholder）；否则切换后占位符还是旧的。
- 别用
id或class当翻译键——语义混乱，后期改文案容易漏掉 - 键名建议用英文小写+下划线，避免空格或中文，方便后续对接国际化工具
- 初始 HTML 里可以写默认语言的文案（比如中文），作为加载前的 fallback，也利于 SEO 和无 JS 场景
JSON 语言包怎么组织和加载
把每种语言存成独立文件，比如 locales/zh.json、locales/en.json，结构必须完全一致：
立即学习“前端免费学习笔记（深入）”；
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
{ "header_title": "欢迎来到我们的网站", "btn_submit": "提交" }
加载时用 fetch()，别硬编码在 JS 里——否则增删语言要改代码，且无法利用浏览器缓存。
- 路径拼接别写死：用
./locales/${lang}.json，而不是./zh.json，否则加日语就得改逻辑 - 加
try/catch包裹fetch和response.json()，网络失败或 JSON 格式错会导致整个翻译中断 - fallback 必须有：如果用户选了
zh-HK但只有zh.json，就降级加载zh.json，否则页面会空白
切换时必须同步改哪些东西
只替换文本是不够的。用户切到日语，屏幕阅读器、字体回退、拼写检查全还按中文走，体验就断了。
- 必须更新
document.documentElement.lang，比如设为"ja"或"zh-Hans" - 所有带语言信息的子元素（比如代码块里的
<pre lang="bash">）不能被连带影响——lang是继承机制，不是全局开关，局部内容得自己显式写lang属性 -
localStorage.setItem('lang', 'ja')要在加载成功后再执行，否则用户刷新页面可能拿到未加载完的语言包 - 别用
window.location.reload()强刷——破坏前进/后退栈，且没解决动态内容（如用户昵称、时间）的重译问题
为什么下拉菜单
原生 <select> 本身不触发跳转或重渲染，必须配 JS 才能干活，但很多人忽略几个关键点：
-
<option value="zh-CN">的 value 必须是标准 BCP 47 标签，zh_CN或chinese会导致后续匹配失败 - 切换后若只是改
location.href，但没同步更新document.documentElement.lang，屏幕阅读器仍读中文音调 - 拼 URL 很容易出双斜杠错误，比如从
/blog/2024/跳到/ja//blog/2024/，应统一用new URL('/ja' + pathname, location.origin)构造 - 更严重的是：强行覆盖用户系统语言偏好（比如日本用户用英文系统却硬切日文），属于反模式——应优先尊重
navigator.language，再 fallback 到 localStorage
真正容易被忽略的，是混合内容场景：静态文案可预加载 JSON 替换，但用户生成内容（如评论、昵称）、实时时间格式、数字分组符号这些，必须运行时调用 Intl.DateTimeFormat 或 Intl.NumberFormat，没法靠 data-i18n 一把梭。
