HTML组件库国际化需三要素：data-component为唯一可靠锚点，data-i18n按字段粒度显式声明，data-version校验语言包与DOM结构一致性，并同步更新各元素lang属性。
HTML组件库的国际化维护，核心不是加语言包，而是让每个组件自己“认得清自己、说得清自己、改得稳自己”——data-component、data-i18n 和 data-version 三者缺一不可。
data-component 必须作为国际化锚点，不能只靠 class 或 id
组件内部文本替换（比如按钮文案从“提交”变“Submit”）若只依赖 .btn 类名，一旦 CSS 被覆盖、类名被删、或多个组件共用同一 class，document.querySelectorAll('.btn') 就会选错范围，导致部分组件没更新、部分被误刷。更糟的是，JS 初始化逻辑可能因 DOM 查询失效而跳过。
-
data-component是唯一可靠的模块标识：它不参与样式、不触发渲染、不被 CSS 规则干扰，且天然支持多实例 - 每个组件根元素必须带
data-component="c-button"这类语义化值，禁止用泛化名如"button"或"ui-btn" - 国际化函数应基于
document.querySelectorAll('[data-component="c-button"]')查找目标，而非类名或层级路径 - 禁用
id做组件定位——循环渲染时必然重复，document.getElementById()只返回第一个，不可靠
data-i18n 属性必须按字段粒度显式声明，不能靠父级继承
一个 c-modal 组件里，标题、确认按钮、取消按钮、输入框 placeholder、错误提示 title 属性，全都需要独立标记。浏览器不会把 data-i18n 当作 CSS 属性那样继承，也不会自动映射到非 textContent 的属性上。
- 主文本用
data-i18n="modal.confirm_title"，对应 JSON 中键名 - placeholder 必须写
data-i18n-placeholder="form.email_placeholder" - alt 文本用
data-i18n-alt="icon.search"，title 用data-i18n-title，以此类推 - 动态插入的节点（如 AJAX 加载的
c-table-row）插入后必须立即调用翻译函数，否则data-i18n不会自动生效 - 不要在
<script></script>、<style></style>、<pre class="brush:php;toolbar:false;"></pre>内部加data-i18n——这些节点不渲染为可见文本，替换无效
data-version 控制接口契约，避免语言包升级引发组件错乱
当组件结构变更（比如从单按钮升级为带图标+文字的复合按钮），旧语言包里的键可能缺失，新语言包字段可能未对齐，仅靠 key 存在与否判断，会导致文案留白或错位。这时 data-version 就是安全阀。
立即学习“前端免费学习笔记（深入）”；
- 组件根元素同时带
data-component="c-button" data-version="2.1" - 语言包文件按版本组织，如
locales/c-button/v2.1/zh.json，键名严格与该版本 DOM 结构对齐 - 加载时校验：
if (langPack.version !== el.dataset.version)则跳过该组件翻译，或降级 fallback 到 v2.0 包 - CI 流程可扫描所有 HTML 片段，比对
data-version与对应语言包目录是否存在，提前拦截不匹配部署 - 禁止把版本号硬编码进 JS 逻辑——它必须来自 DOM，确保 HTML 与语言资源真正同步
切换语言时，lang 属性必须逐层同步，不能只改 documentElement
只执行 document.documentElement.lang = 'en'，对已有子节点完全无效。屏幕阅读器、字体回退、标点间距、甚至某些 CSS :lang() 选择器，都依赖每个元素自身的 lang 属性，不是继承来的。
- 切换前先收集所有已设
lang的元素：document.querySelectorAll('[lang]') - 遍历并更新：对明确需随主语言切换的节点（如导航、正文），设
el.lang = newLang；对保留原语言的节点（如<pre class="brush:php;toolbar:false;" lang="bash"></pre>、引用外文段落），跳过 -
document.documentElement.lang必须设为 BCP 47 标准码（如zh-Hans、ja），zh_CN或chinese会被浏览器忽略 - 动态插入含
lang的节点（如代码块、引文）时，必须在插入前就写好正确值，不能靠后续统一刷
最易被忽略的一点：组件内嵌的 <template></template> 不会自动继承外部 lang，也不响应 documentElement.lang 变更——它里面的文本节点必须在克隆后、插入前，由组件自身完成 data-i18n 解析和 lang 属性设置。
