data-i18n标记必须覆盖所有可翻译属性，不只是textContent；placeholder、alt、title等需显式加对应后缀（如data-i18n-placeholder）；lang属性须逐节点设置且不可仅改documentElement；动态DOM需手动触发翻译；JSON加载须有fallback机制。
data-i18n标记必须覆盖所有可翻译属性，不只是textContent
只给 <h1 data-i18n="welcome">欢迎</h1> 加 data-i18n 是不够的。浏览器不会自动把键映射到 placeholder、alt、title 或 aria-label 上——这些属性完全独立于 textContent。
常见翻车现场：<input placeholder="Search"> 切换语言后还是英文；<img alt="user avatar"> 的替代文本没变；<label for="email">Email</label> 文字翻了但 for 属性没同步，导致点击 label 失效。
- 必须显式加对应后缀：如
data-i18n-placeholder="search_hint"、data-i18n-alt="avatar_desc"、data-i18n-title="tooltip_info" -
value属性一般不翻译（属于用户输入数据），跳过处理；但<button>和<input type="submit">的显示文案建议统一用textContent更新，避免value被意外提交 - 含 HTML 结构的文案（如“请阅读服务条款”）必须用
innerHTML替换，且语言包里对应值要是可信纯 HTML 片段（不能带用户输入、不执行 JS），否则有 XSS 风险
lang属性必须显式设在每个含文本的语义化标签上
只改 document.documentElement.lang = 'zh-Hans' 不会改变页面渲染行为。屏幕阅读器仍读错、顿号按英文间距排版、中文字体覆盖 <pre lang="bash"> 里的代码字体——这不是国际化，只是改了个标签。
浏览器和屏幕阅读器按每个元素自身的 lang 属性决定标点宽度、连字规则、字体回退链、语音朗读方式，不继承父级。
立即学习“前端免费学习笔记（深入）”；
- 所有含文本的语义化标签（
<h1>、<p>、<section>、<footer>等）都必须显式写lang，值与当前语言包一致（如lang="zh-Hans"） - 已有
lang的特殊元素（如<pre lang="bash">、<code lang="sql">）切换语言时保留原值，这是多语言混排的合法场景 -
<script>和<style>内部不要写lang，它们不参与文本渲染，设了也白设
动态插入的 DOM 必须手动触发翻译，不会自动监听
AJAX 加载的弹窗、表格行、懒加载模块插入后，如果没调用翻译函数，里面的 data-i18n 标记就只是字符串，不会变成对应语言文本。
典型失效场景：<modal> 点击打开后，内部 <h2 data-i18n="modal_title"> 不更新；分页表格每页 AJAX 获取新 <tr>，新行里的 data-i18n 保持原始键名。
- 插入新节点后，必须立即遍历并调用翻译逻辑（例如
translateElement(newNode)） - 不要依赖
MutationObserver自动监听——它无法区分哪些是翻译节点，也无法保证执行顺序，更无法处理lang属性同步 - 第三方组件（如日期选择器）若支持 i18n，需单独调用其 locale 方法（如
flatpickr.set("locale", "zh")），不能指望 DOM 批量替换生效
JSON语言包加载失败或 key 缺失时，必须有 fallback 机制
fetch('./locales/zh.json') 报 TypeError: Failed to fetch 或返回 404，又没兜底，整个页面文案就会留空——用户看到的是一堆 data-i18n="xxx" 键名。
更隐蔽的问题是：某语言文件漏写一个 key（比如 "btn_submit": "" 没填），JS 查不到就返回 undefined，最终渲染成空字符串或 undefined 文本。
- 加载时必须用
try/catch包住fetch()，捕获网络层错误；再用response.ok判断 HTTP 状态码是否为 2xx - key 查询必须 fallback：先试完整码（如
zh-HK），再截主语言（zh），最后退到默认语言（如en） - 所有语言 JSON 文件键名必须严格一致；某语言暂未翻译也要保留键，设为空字符串：
"btn_submit": ""，否则查不到 key 就留白
Intl.DateTimeFormat）这五件事必须同步更新，缺一不可。任何一项滞后，都会导致语音、字体、标点、时间显示或文案内容出错——而且这种错往往只在特定设备、辅助技术或网络条件下才暴露。 
