lang属性必须显式写在每个含文本的语义化标签上，仅设置document.documentElement.lang无效；data-i18n需覆盖所有可翻译属性（如placeholder、alt等），动态插入DOM后须手动调用翻译函数；语言包加载须校验content-type并设fallback。
lang属性必须显式写在每个语义化容器上
只改document.documentElement.lang，对已渲染的文本完全没用。浏览器和屏幕阅读器不继承父级lang，而是逐个检查每个元素自身的lang值来决定标点宽度、字体回退链、连字规则和语音朗读方式。
常见错误现象：<p>里的中文顿号按英文间距渲染；<pre lang="bash">被中文字体覆盖；<img alt="logo">的alt文本仍被读作英文。
- 所有含文本的语义化标签（
<h1>、<p>、<section>、<footer>等）都必须显式加lang，值与当前语言包一致（如lang="zh-Hans"） - 已有
lang的特殊元素（如<pre lang="bash">、<code lang="sql">）切换语言时保留原值，这是合法的多语言混排场景 -
<script>和<style>内部不要写lang，它们不参与文本渲染，设了也白设
data-i18n必须覆盖所有可翻译属性，不只是textContent
data-i18n默认只替换元素的textContent，对placeholder、alt、title、aria-label等属性完全无效——漏掉任何一个，就会导致对应内容卡在旧语言。
常见错误现象：<input placeholder="Search">切换后仍是英文；<img alt="user avatar">的替代文本没更新；<label for="email">Email</label>文字翻了但for没同步，点击失效。
立即学习“前端免费学习笔记（深入）”；
- 每个要翻译的元素至少有一个基础
data-i18n键；含placeholder就额外加data-i18n-placeholder；同理data-i18n-title、data-i18n-alt -
value属性一般不翻译（属于用户输入数据），但<button>和<input type="submit">的显示文案建议统一用textContent更新，避免value被意外提交 - 含HTML结构的文案（如“请阅读服务条款”）必须用
innerHTML替换，且语言包里对应值要是可信纯HTML片段（不能带用户输入、不执行JS），否则有XSS风险
动态插入的DOM必须手动触发翻译
AJAX加载的弹窗、分页表格新行、懒加载模块插入后，data-i18n标记不会自动生效——它只是字符串，不是指令。没人调用翻译函数，就不会替换。
常见错误现象：点击按钮打开的<modal>里<h2 data-i18n="modal_title">保持原始键名；分页表格每页新<tr>里的data-i18n始终是英文键。
- 插入新DOM后立即遍历其子节点，调用翻译函数处理所有
data-i18n*属性 - 推荐封装成工具函数，例如
translateNode(node)，支持递归处理子树 - 不要依赖MutationObserver自动监听——开销大、易漏、无法保证执行时机
语言包加载必须校验content-type并设置fallback
把语言包硬编码进JS或用XMLHttpRequest忽略MIME类型，容易静默失败：404返回HTML页面、服务器错配text/plain、CDN缓存脏数据……都会导致整页文案留白。
常见错误现象：切换到zh-HK后页面变空；本地开发正常，上线后部分语言加载失败。
- 语言包路径统一为
./locales/${lang}.json（如./locales/zh-HK.json） - 必须用
fetch()+try/catch，检查response.ok和response.headers.get('content-type')?.includes('application/json') - fallback顺序：先试完整BCP 47码（
zh-HK），再截主语言（zh），最后退到en；所有语言文件键名必须严格一致，未翻译项留空字符串
lang写错一个字符，标点就乱；data-i18n-alt漏写一次，屏幕阅读器就报错；动态DOM插完不手动翻译，用户看到的就是原始键名。这些细节不补全，国际化就只是表面功夫。 
