data-i18n 标记需覆盖所有可翻译属性，必须显式声明 data-i18n-placeholder、data-i18n-alt 等后缀；语言包须扁平结构、键名对齐、BCP 47 命名；切换语言时须同步更新 document.documentElement.lang 及所有子元素 lang 属性，并重建 Intl 实例、恢复滚动位置。
data-i18n 标记必须覆盖所有可翻译属性，不只是 textContent
只给 <h1 data-i18n="home.title"> 加属性，切换后 <input placeholder="Search"> 还是英文——这是最常见翻车点。浏览器不会自动把 data-i18n 映射到 placeholder 或 alt 上。
必须显式声明对应后缀：
-
data-i18n-placeholder用于input、textarea -
data-i18n-title用于 tooltip 类提示 -
data-i18n-alt用于<img>替代文本 -
data-i18n-aria-label用于无障碍标签 -
value属性一般跳过（属于用户输入数据），但<button>和<input type="submit">的显示文案建议用textContent更新
含 HTML 结构的文案（如“请阅读服务条款”）需用 innerHTML 替换，但语言包里对应值必须是可信纯 HTML 片段，不能拼接用户输入，否则有 XSS 风险。
JSON 语言包结构必须扁平 + 键名对齐 + BCP 47 命名
语言包不是随便写个对象就行。zh.json 里有 "form.submit"，en.json 里漏了这键，JS 查不到就留空；某语言暂时没译完，也得保留键并设为空字符串："form.submit": ""，否则整个字段消失。
立即学习“前端免费学习笔记（深入）”；
路径和命名要严格统一：
- 文件路径固定为
./locales/zh-Hans.json、./locales/en-US.json（注意是连字符，不是下划线） - 键名全小写+英文点号分隔，如
nav.home、error.network_timeout，禁用中文或空格 - 避免嵌套：不要
{"common": {"submit": "提交"}}，而用{"common.submit": "提交"} - HTTP 返回时
Content-Type必须是application/json，否则fetch()可能静默失败
切换语言时必须同步更新 document.documentElement.lang 和所有子元素 lang 属性
只改 document.documentElement.lang = 'zh-Hans'，页面文字不会变，屏幕阅读器仍读英文，标点间距错乱，中文字体回退失效——因为浏览器和辅助技术按**每个元素自身的 lang 属性**决定行为，不继承。
正确做法是遍历并同步更新：
- 所有带
lang的语义化标签（<p>、<section>、<footer>等）都需设为当前语言码，如lang="zh-Hans" - 已有明确多语言内容的元素（如
<pre lang="bash">、<code lang="sql">）保留原lang值，不参与更新 -
<script>和<style>内部不加lang，它们不参与文本渲染 - 动态插入的 DOM（弹窗、AJAX 表格行）插入后必须立即调用翻译函数，MutationObserver 不可靠，无法触发翻译
动态内容、表单状态、滚动位置必须保留在切换过程中
用 window.location.reload() 切语言？表单输入清空、路由重置、滚动跳顶——用户立刻想关网页。真正可用的切换是局部刷新。
关键动作要一次做完：
- 切换前用
getComputedStyle(document.scrollingElement).scrollTop记录滚动位置 - 更新所有
data-i18n*绑定的属性 + 同步lang属性 - 调用
Intl.DateTimeFormat和Intl.NumberFormat重建实例（旧实例不会自动响应语言变更） - 恢复滚动：
window.scrollTo(0, savedScrollTop) - select 的
option文字需单独处理：遍历select[data-i18n] option，查语言包中"xxx.options"数组逐个赋值
最容易被忽略的是：SVG 内嵌文本（<text>下载</text>）、第三方组件（如日期选择器）的语言同步，这些必须在切换后手动触发更新，没有通用监听机制。
