HTML多语言切换依赖结构设计与运行时更新，核心是data-i18n标记键值、BCP 47规范语言包、同步document.documentElement.lang及Intl API、第三方组件locale更新和辅助技术适配。
HTML 标签本身不直接支持多语言切换，国际化靠的是结构设计 + 数据驱动 + 运行时更新，不是改标签名或加属性就能生效。
data-i18n 属性是工程化落地的起点
用 data-i18n 标记需要翻译的节点，是最轻量、最解耦的方案。它不侵入 DOM 结构，也不依赖框架，纯 HTML 可写可读。
-
data-i18n的值是键（key），比如"nav.home"或"article.date"，不是翻译文本本身 - 键名建议按模块+语义分层，避免扁平如
"btn1"、"text2"—— 后期维护会崩溃 - 同一个键可在多个元素复用（比如多处“首页”都用
data-i18n="nav.home"），但要确保翻译值语境一致 - 不要把
data-i18n和class混用做样式控制——它只管语义，样式走 CSS
JSON 语言包必须按 BCP 47 规范组织
语言包不是随便建个 zh.json 就完事。浏览器 navigator.language 返回的是 zh-CN、en-US、ja-JP 这类带区域码的标识，JSON 文件名必须严格匹配。
- 推荐文件结构：
locales/zh-CN.json、locales/en-US.json、locales/zh-HK.json - 键路径支持嵌套，比如
{"common": {"submit": "提交"}}，对应data-i18n="common.submit" - 避免在 JSON 中放 HTML 片段；若必须保留内联标签（如
<strong>），需前端做白名单过滤，否则有 XSS 风险 - 服务端渲染（SSR）场景下，JSON 内容应预编译进页面，而非全量 JS 加载，减少 FOUC
切换语言时不能只改 textContent
单纯遍历所有 data-i18n 元素并设 textContent，会破坏已有交互逻辑。真实项目里，至少三类内容必须同步处理：
立即学习“前端免费学习笔记（深入）”；
-
<time datetime="2026-07-09"></time>类元素：需调用Intl.DateTimeFormat重格式化，不能只换文字 -
<input placeholder="搜索">：placeholder 是属性，得用el.setAttribute('placeholder', ...)，不是textContent - 第三方组件（如日期选择器、富文本编辑器）：它们内部语言状态独立，必须触发其 locale 更新方法，比如
flatpickr.set('locale', 'zh') - 别忘了同步更新
document.documentElement.lang，否则屏幕阅读器无法切换语音库
lang 属性和 documentElement.lang 是硬性依赖点
<html lang="zh-CN"> 不只是给 SEO 看的，它是整个页面语言上下文的锚点。所有基于 Intl 的 API（Intl.NumberFormat、Intl.RelativeTimeFormat）默认读取这个值。
- 首次加载时，优先从服务端注入
lang值（通过 Accept-Language 解析），而不是信任navigator.language - 用户手动切换语言后，必须同时更新
document.documentElement.lang和 localStorage，但 localStorage 仅作 fallback，不能替代服务端决策 - React/Vue 等框架中，不要用
useState或ref存语言状态来驱动 DOM —— 它们不触发documentElement.lang变更，辅助技术就失效
真正难的不是替换文字，而是让时间、数字、顺序、表单提示、第三方组件、辅助技术全部响应一次语言变更——这要求你把 lang 当成全局状态变量，而不是 UI 层的一个 props。
