lang属性必须显式设在每个含文本的语义化标签上，仅改document.documentelement.lang无效；data-i18n需覆盖所有可翻译属性并加对应后缀；动态插入dom须手动触发翻译；lang值必须符合bcp 47标准（如zh-hans）。
lang 属性必须显式设在每个含文本的语义化标签上
只改 document.documentElement.lang，对已渲染的 <p></p>、<h2></h2>、<label></label> 等元素完全无效。浏览器和屏幕阅读器按每个元素自身的 lang 属性决定标点宽度（如中文顿号 vs 英文 comma）、字体回退链、连字规则、语音朗读方式——不继承父级。
常见错误现象：<p>欢迎使用</p> 切换为中文后仍被 VoiceOver 读作英文；<pre class="brush:php;toolbar:false;" lang="bash">npm install</pre> 里的等宽字体被中文字体覆盖；<blockquote lang="fr">Merci</blockquote> 的法语引号间距错乱。
- 所有含文本的语义化标签（
<h1></h1>、<p></p>、<section></section>、<footer></footer>、<label></label>）都必须显式写lang，值与当前语言包一致（如lang="zh-Hans"） - 已有
lang的特殊元素（如<pre class="brush:php;toolbar:false;" lang="bash"></pre>、<code lang="sql">）切换语言时保留原值，这是多语言混排的合法场景 -
<script></script>和<style></style>内部不要写lang，它们不参与文本渲染，设了也白设
data-i18n 属性必须覆盖所有可翻译属性，不只是 textContent
data-i18n 默认只作用于元素的 textContent，对 placeholder、title、alt、aria-label 等属性完全无效。常见错误是只给 <input> 加 data-i18n，结果 placeholder 还是英文。
使用场景：表单控件、SVG 文本、按钮文案、图片替代文本都需要独立标记。
- 必须显式加对应后缀：
data-i18n-placeholder="search_hint"、data-i18n-alt="avatar_desc"、data-i18n-title="tooltip_info" -
value属性一般不翻译（属于用户输入数据），跳过处理；但<button></button>和<input type="submit">的显示文案建议统一用textContent更新，避免value被意外提交 - 含 HTML 结构的文案（如“请阅读服务条款”）必须用
innerHTML替换，且语言包里对应值要是可信纯 HTML 片段（不能带用户输入、不执行 JS），否则有 XSS 风险
动态插入的 DOM 必须手动触发翻译，不会自动监听
使用 AJAX 加载的弹窗、表格行、懒加载模块插入后，如果没调用翻译函数，里面的 data-i18n 标记就只是字符串，不会变成对应语言文本。
常见错误现象：点击按钮打开的 <modal></modal>，内部 <h2 data-i18n="modal_title"></h2> 不更新；分页表格每页 AJAX 获取新 <tr>，新行里的 <code>data-i18n 保持原始键名。
- 弹窗、模态框、Tab 面板等动态插入内容，需在
appendChild或insertAdjacentHTML后立即遍历并调用翻译逻辑 - 不要依赖
MutationObserver自动监听——它无法捕获属性值变更（如data-i18n值本身没变，只是语言包换了），也无法区分是否已翻译过 - 若用框架（如 Vue/React），确保翻译逻辑在组件挂载或 DOM 插入完成后的生命周期钩子中执行
lang 值必须符合 BCP 47 格式，错误比不写更糟
lang="zh_CN"、lang="chinese"、lang="zh" 这类非标准值会被浏览器忽略，导致标点渲染异常、字体 fallback 失效、屏幕阅读器读错——这不是国际化，只是改了个标签。
性能影响：错误的 lang 值会让浏览器放弃优化路径，强制走通用字体回退，中文页面可能默认用等宽字体渲染正文，体验明显劣化。
- 必须用 BCP 47 标准码：
zh-Hans（简体中文）、zh-Hant（繁体中文）、ja-JP、en-US；iOS VoiceOver 对ja支持差，得写ja-JP - 局部多语言内容（如英文术语、日文引用、代码块）必须显式写内联
lang，例如<code lang="en">useState或<blockquote lang="fr"></blockquote> - 切换语言后，要遍历所有带
lang的元素，把非根节点的lang值也同步更新（比如博客里一段lang="ja"的引文，不能跟着主语言切成lang="zh-Hans"）
lang」，而是「每个可见文本节点都有正确、合规、不冲突的 lang」——漏掉一个 <label></label> 或写错一个 lang="zh"，就可能让整段中文标点间距错乱、屏幕阅读器跳过关键提示。前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
