data-i18n 属性需覆盖所有可翻译 dom 属性，包括 placeholder、title、alt、value 等，且须带对应后缀；lang 属性必须逐节点更新以确保辅助技术与 css :lang() 生效；bcp 47 格式须严格；json 加载失败需 fallback 防空白；切换时须保持表单状态、滚动位置及动态内容同步翻译。
data-i18n 属性必须覆盖所有可翻译的 DOM 属性
只给 <h1 data-i18n="header_title"></h1> 加属性，其他文案不会变——placeholder、title、alt、value 这些属性完全不受 textContent 更新影响。JS 替换时若不显式处理，切换后搜索框占位符还是旧语言。
常见漏点包括：
-
<input data-i18n-placeholder="search_hint">—— 必须带-placeholder后缀，不能指望通用逻辑自动识别 -
<button data-i18n="btn_submit" data-i18n-value="btn_submit"></button>—— 某些浏览器渲染时优先取value，textContent被忽略 -
<label data-i18n="form_email"><input></label>——label文字必须标记，否则屏幕阅读器读不到新文本 -
<select data-i18n="country_select"><option value="CN">中国</option></select>——option文字需单独遍历替换，不能只靠父级键名
lang 属性不能只改 document.documentElement.lang
执行 document.documentElement.lang = 'zh-Hans' 后，页面看起来像切了语言，但屏幕阅读器仍用旧语音引擎读英文术语，:lang(zh-Hans) CSS 选择器也不生效——因为浏览器和辅助技术在 DOM 解析初期就锁定每个节点自身的 lang 值，不响应运行时继承更新。
必须同步遍历并重设所有已存在的 lang 属性：
-
<p lang="en">API</p>→ 切换时需判断是否要保留（如术语引用），否则改为lang="zh-Hans" -
<pre class="brush:php;toolbar:false;" lang="bash"></pre>→ 这类技术语种通常不随主语言变，应加data-keep-lang显式跳过 -
<blockquote lang="ja"></blockquote>→ 若为引用内容，保留原lang；若是用户生成内容，则需同步更新
BCP 47 格式必须严格：用 zh-Hans，不是 zh_Hans 或 chinese，否则 :lang() 和浏览器翻译直接忽略。
JSON 语言包加载失败会导致整页留空
fetch 失败或 key 缺失时，langPack[key] 返回 undefined，赋给 textContent 就是空字符串——用户看到的不是“未翻译”，而是大片空白或原始键名（如 header_title）。
防崩关键动作：
- 路径拼接用
./locales/${lang}.json，别硬编码./zh.json - 加
try/catch包住整个fetch()+response.json()流程 - 所有语言文件结构必须扁平且键名对齐：
{"header_title": "首页", "btn_submit": "提交"}✅；嵌套结构或缺失字段 ❌ - fallback 分两级：先试
zh-HK→ 降级zh→ 最终退到内置默认对象（如{header_title: "Home"}）
切换时必须保持表单状态和滚动位置
语言切换不是简单重载页面或暴力替换所有文本。关键在于保持当前路由、表单输入值、滚动位置、以及第三方组件（如日期选择器）的语言同步。
做法是监听语言变更后，只触发一次「局部刷新」：
- 遍历所有带
data-i18n的元素，查表更新其内容 - 同时调用
Intl.DateTimeFormat或Intl.NumberFormat重建格式化实例（不能复用旧对象） - 切换前用
getComputedStyle记录当前滚动位置，更新完 DOM 后用window.scrollTo()恢复，否则页面会跳回顶部 - 如果用了
moment.js，记得调用moment.locale('en')；若用原生Intl，需重建所有格式化实例
真正容易被忽略的是：动态插入的 DOM（比如 AJAX 加载的弹窗、列表项）不会自动被翻译，必须在插入后手动触发翻译函数；SVG 内部的 <text></text> 元素也得单独处理，它不响应常规 data-i18n 遍历逻辑。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
