页面加载时必须主动读取 localstorage 中的 'preferred-lang' 并立即应用语言状态，否则跨页跳转会重置为默认语言；需依次 fallback 到 url 参数和 navigator.language，再调用 applylang() 更新文本、document.documentelement.lang 及 ui 状态。
必须在页面加载时主动读取 localStorage 并立即应用语言状态，否则跨页跳转后会重置为默认语言——这是纯前端多页站点最常漏掉的一环。
页面加载时必须执行初始化还原
用户切换语言后写入 localStorage.setItem('preferred-lang', 'ja')，但这只是“存”，不是“用”。新页面打开时 JS 从头执行，不读这个值，就永远 fallback 到 navigator.language 或硬编码的默认值。
- 初始化逻辑要独立于点击事件，放在脚本最外层或
DOMContentLoaded回调里 - 先读
localStorage.getItem('preferred-lang')，再 fallback 到 URL 参数new URLSearchParams(window.location.search).get('lang')，最后才是navigator.language?.split('-')[0] || 'en' - 拿到语言码后，立刻调用翻译函数（如
applyLang('ja')），更新所有data-i18n元素、document.documentElement.lang和语言切换按钮的激活态
切换语言时要同步更新三处关键状态
只改文本不持久、只存 localStorage 不更新 UI、只切语言不设根节点 lang 属性，都会导致可访问性失效或 SEO 漏失。
- 更新
localStorage：确保下次加载能读到最新值 - 设置
document.documentElement.lang = 'zh-Hans'（注意必须是 BCP 47 格式，zh_CN无效） - 遍历并更新所有已有
lang属性的子元素（如引文<p lang="ja"></p>），避免它们被全局语言覆盖；局部多语言内容需显式保留原lang值
data-i18n 属性必须覆盖所有可读文本位置
漏标一个 placeholder 或 title，切换后就会显示英文，用户会觉得“没切成功”——其实只是你没告诉 JS 去动它。
-
data-i18n只影响textContent，对input的placeholder、img的alt、a的title无效 - 必须用带后缀的写法：
data-i18n-placeholder="search.hint"、data-i18n-title="tooltip.close" -
value属性一般不翻译（属于用户输入数据），但label文本必须标data-i18n - 动态插入的 DOM（如弹窗、AJAX 加载的列表项）插入后要手动调用翻译函数，不会自动监听
JSON 语言包加载失败时要有明确 fallback
网络抖动、路径写错、MIME 类型不对（服务器没返回 Content-Type: application/json）都会让 fetch('./locales/ja.json') 静默失败，最终页面留白。
- 每个语言文件路径必须统一，如
./locales/${lang}.json，不要混用zh-CN.json和zh.json - 加载时用
try/catch包裹fetch()和response.json()，失败则降级到主语言码（如ja-JP加载失败，试ja） - 所有语言包键名必须严格对齐，缺字段就留空字符串
"btn_submit": ""，不能直接删键，否则查不到就渲染为空 - 服务端返回 JSON 时务必设置正确
Content-Type，否则现代浏览器可能拒绝解析
最容易被忽略的是：语言切换后，屏幕阅读器仍按旧 lang 属性朗读，因为它是逐元素生效的，不是继承的。不批量更新子元素的 lang，等于没切。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
