data-i18n + 外部 JSON 是解耦的物理边界：用 data-i18n 属性标记需翻译节点，翻译值存于外部 zh.json/en.json 中，键为纯字符串且层级≤2，切换语言仅更新文本、保留状态，并通过服务端 Accept-Language 注入 lang 属性确保 SSR/CSR 一致。
data-i18n + 外部 JSON 是解耦的物理边界
把翻译文本塞进 JS 字符串或 HTML 注释里，等于把语言配置和逻辑代码焊死在一起。真正解耦的第一步，是让翻译内容完全脱离 HTML 和 JS 的执行路径——data-i18n 属性就是这个锚点。
它不参与渲染、不触发样式、不绑定事件，只做一件事：标记“这里需要翻译”。对应的语言值全放在外部 zh.json、en.json 里，按键查表即可。构建时甚至可以交给 CI 自动校验键是否缺失，而不用打开 HTML 文件一行行对。
-
data-i18n值必须是纯字符串键（如"header.welcome"），禁止拼接变量或表达式，否则无法静态分析 - JSON 文件禁止嵌套过深，层级建议 ≤2 层（
{"form": {"submit": "提交"}}可，{"pages": {"home": {"sections": {"hero": {...}}}}}不可） - 键名中避免用空格、中文、特殊符号；推荐用英文点号分隔，既符合 JS 路径习惯，也方便后续转成 TS 类型定义
切换语言时只刷新 DOM 文本，不重载、不重建
语言切换不是 reload 页面，也不是清空再 render 整个 document.body。核心动作就一个：遍历所有带 data-i18n 的节点，查新语言包，更新 textContent 或安全地设置 innerHTML。
这么做能保住所有已绑定的事件监听器、表单输入值、滚动位置，以及第三方组件（比如 flatpickr 或 Chart.js 实例）的状态。
立即学习“前端免费学习笔记（深入）”；
- 优先用
el.textContent = value，只有当翻译值含 HTML 标签（如"请<a href="https://www.php.cn/link/93ac0c50dd620dc7b88e5fe05c70e15b">登录</a>继续"）时，才用el.innerHTML = value，且必须提前做过滤或白名单处理 - 切语言后，必须同步更新
document.documentElement.lang，否则屏幕阅读器、CSS:lang()选择器、Intl实例都会不同步 - 时间/数字/货币字段需单独调用
Intl.DateTimeFormat或Intl.NumberFormat重建实例，旧对象不会自动响应语言变更
服务端注入 lang 属性才是 SSR 和 CSR 一致的起点
只靠 navigator.language 判断用户语言，在 SSR 场景下必然错乱——服务端根本没这个 API。浏览器隐私模式、手动改过语言设置、甚至某些安卓 WebView 都会让这个值不可信。
正确做法是：服务端从 Accept-Language 请求头解析出首选语言，直接写进 HTML 的 <html lang="zh">，前端初始化时优先读它，fallback 才用 navigator.language。
- Node.js 后端推荐用
accepts库解析，比手写正则更准，支持权重（zh-CN;q=0.9,en;q=0.8） - 不要用
localStorage存语言偏好来覆盖服务端判断——首次访问没值，且设备更换后状态丢失 - 用户手动切换语言后，应发请求到
/api/locale同步服务端，否则后续接口返回的错误消息仍是旧语言
模块级 data-component + i18n 键前缀才能支撑多实例复用
一个页面里可能有多个搜索框、多个商品卡片，每个都要独立支持语言切换。如果只用全局键 "search.placeholder"，所有搜索框会显示同一段文字，无法差异化。
解决方案是把 data-component 和 i18n 键绑定：给每个模块根元素加 data-component="search-bar"，翻译键就变成 "search-bar.placeholder"，加载时按组件作用域查表。
-
data-component必须设在模块最外层容器上，不能写在内部某个<p>上 - 组件内多个需翻译节点，统一用该组件名打头，避免键冲突（如
"product-card.title"、"product-card.price"） - 若组件支持多语言动态 props（比如卡片标题可由数据传入），则跳过
data-i18n，直接用 JS 拼接键并查表，而非硬编码在 HTML 中
