组件化多语言重构需绑定data-i18n到组件边界，按组件粒度加载扁平语言包，显式同步lang属性，安全更新动态内容，并确保语言状态隔离。
data-i18n 标记必须绑定到组件边界，不能只扫 DOM 节点
组件化重构的核心不是“把所有 data-i18n 加一遍”，而是让每个可复用区块（如 cmp-card、cmp-banner）自身具备语言适配能力。否则，同一段翻译逻辑在不同页面重复初始化，容易漏掉动态插入的子节点或覆盖错 scope。
常见错误现象：全局遍历 [data-i18n] 替换文本，结果弹窗里的按钮文案没更新，因为弹窗 DOM 是 later 插入的；或者卡片组件被复制到英文页后，里面的 data-i18n="card_title" 还指向中文键名。
- 每个组件外层容器必须带唯一类前缀，如
class="cmp-card"，且该容器本身要带data-i18n-scope="card"（值可任意，但需与语言包键前缀一致） - 组件内所有
data-i18n键名应统一加前缀，如card_title、card_cta，避免和nav_home冲突 - 初始化时只翻译当前组件范围：
el.querySelector('.cmp-card').querySelectorAll('[data-i18n]')，而不是document.querySelectorAll - 组件销毁前清空已绑定的事件或定时器，防止切换语言时旧实例干扰新渲染
lang 属性必须随组件生命周期同步，不是一次性设置
组件化场景下，一个页面可能同时存在中、英、日三语内容（比如文档页含代码块 、引用段落 、主文案 ）。只改 document.documentElement.lang 会让所有子组件误判语言环境。
实操建议：
- 组件挂载时，显式设置其根容器的
lang属性，值来自当前语言上下文（如zh-Hans），而非继承父级 - 组件接收语言变更通知后，只更新自己内部的
lang和data-i18n文本，不触及其他组件 - 对明确多语言混排的子元素（如
<pre class="brush:php;toolbar:false;" lang="sql"></pre>、<code lang="js">），初始化时跳过lang同步，保留原始值 - 避免在组件 JS 里硬编码
document.documentElement.lang = 'en'—— 这会污染全局，破坏其他组件的语言隔离
语言包加载要按组件粒度拆分，别全量加载
纯 HTML 页面用一个 locales/en.json 没问题，但组件化后，首页轮播图、用户中心表单、帮助文档侧边栏，翻译需求完全独立。全量加载会拖慢首屏，也增加 key 冲突风险。
关键差异点：
- 组件定义自己的语言包路径，如
cmp-banner加载./locales/banner/en.json，而非顶层locales/en.json - 语言包结构保持扁平，但键名空间隔离：
{"title": "Banner Title", "cta": "Learn More"}，不嵌套成{"banner": {"title": "https://www.php.cn/link/263b1243ca2dbeb358777ceabc4a2e4c"} } - 组件首次渲染时才 fetch 对应语言包，用
Promise.cache或 Map 缓存已加载文件，避免重复请求 - 加载失败时 fallback 到组件内置默认文案（如
title: "Banner"），而不是抛错或留空
动态内容注入必须走组件 API，不能直接 innerHTML
组件常需渲染列表、表格、富文本等动态内容，若直接 innerHTML = translatedString，会丢失事件监听、破坏已有状态（比如已展开的折叠面板）、引入 XSS 风险。
正确做法：
- 组件暴露
updateI18n(lang)方法，内部只更新 textContent 或安全的 innerHTML（经 DOMPurify 过滤） - 富文本字段（如“请阅读 服务条款”）必须在语言包里提供预转义 HTML 字符串，且组件内用
el.innerHTML = purify.sanitize(translated) - 表单控件（
<select></select>、<input type="radio">）的选项文案，要在组件初始化时批量生成，而非靠data-i18n单个标记 - 不要在组件模板里写
<div data-i18n="list_item">{{item.text}}</div>——data-i18n不处理插值，只会原样显示键名
lang、translations、fallback 当作共享变量传，就等于放弃组件隔离——后续任何一处修改都可能连锁崩塌。前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
