data-i18n属性需按后缀精准匹配可翻译字段：data-i18n控制textcontent/innerhtml，data-i18n-value替换value，data-i18n-title替换title，data-i18n-aria-label替换aria-label；键名须严格一致、小写点分隔；切换语言时须同步更新document.documentelement.lang、遍历更新dom、再存localstorage；动态插入元素需手动或用mutationobserver触发翻译。
data-i18n 属性必须显式标记按钮的可翻译字段
按钮的 textContent、value、title、aria-label 都可能需要翻译，但它们不会被同一套逻辑自动覆盖。只写 <button data-i18n="submit">提交</button> 只能替换文本内容，placeholder、title 等仍保持原样。
正确做法是为不同属性加对应后缀：
-
data-i18n→ 控制textContent或innerHTML -
data-i18n-value→ 替换value（适用于<input type="submit">） -
data-i18n-title→ 替换title属性 -
data-i18n-aria-label→ 替换aria-label
常见错误是漏掉 data-i18n-title，导致鼠标悬停时提示语仍是中文；或把 data-i18n 加在 <input> 上却没配 data-i18n-value，结果按钮显示“Submit”但点击后表单提交按钮文字还是“提交”。
语言包键名要和 HTML 中的 data-i18n 值严格一致
键名不是随便起的，一旦定下就不能改。比如 HTML 里写了 <button data-i18n="form.submit"></button>，那所有语言 JSON 文件里都得有 "form.submit" 这个 key，不能写成 "submit_form" 或 "btn_submit"。
键名建议用英文小写+点号分隔层级（如 form.submit、nav.home），避免空格、大写、中文或下划线开头——这些在某些构建工具或 JSON Schema 校验中会出问题。
如果键缺失，JS 查不到值就会返回 undefined，按钮变成空白。所以语言包加载后，最好加一层 fallback：找不到键时回退到 key 名本身（如显示 “form.submit” 字符串），至少让用户知道哪块漏翻了。
切换时必须同步更新 document.documentElement.lang
只改按钮文字，不改 document.documentElement.lang，会导致屏幕阅读器仍按中文朗读、字体回退策略不变、拼写检查错乱。这不是“锦上添花”，而是可访问性和本地化渲染的硬性要求。
执行切换时，这几件事必须一起做：
- 调用
document.documentElement.lang = 'en'（或'zh-Hans'） - 遍历所有
[data-i18n]元素并更新内容 - 显式处理带后缀的属性（
data-i18n-title等） - 最后才写入
localStorage.setItem('preferred-lang', 'en')
顺序不能错：先设 lang，再更新 DOM，否则浏览器可能在中间状态触发字体重排或语音引擎初始化，造成短暂异常。
动态插入的按钮必须手动触发翻译
页面初始加载时的按钮能被一次性遍历替换，但 JS 后续插入的弹窗按钮、表格操作栏、模态框里的 <button data-i18n="close"></button> 不会自动生效。
解决方法只有两个：
- 插入新 DOM 后立刻调用翻译函数，例如：
modal.appendChild(btn); translateElement(btn); - 用 MutationObserver 监听新增节点，对匹配
[data-i18n]的元素自动调用翻译 —— 但要注意避免重复处理已翻译过的元素
最容易被忽略的是 SVG 内的 <text></text> 或自定义组件封装的按钮，它们往往没加 data-i18n，或者加了但没纳入翻译流程，结果切换语言后按钮变英文，图标旁的文字还是中文。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
