lang属性必须显式设在每个含文本的语义化标签上，data-i18n需覆盖所有可翻译属性（含placeholder/alt等），动态DOM需手动触发翻译，语言包须fetch校验并扁平对齐。
只在 <html> 标签上设 lang 属性，对国际化是无效的——浏览器和屏幕阅读器根本不会继承它，所有文本容器必须各自声明语言。
lang 属性必须显式写在每个语义化容器上
很多团队以为改了 document.documentElement.lang = 'zh-HK' 就万事大吉，结果 <p> 里的顿号还是按英文间距渲染，<pre lang="bash"> 里的代码字体被中文字体覆盖，<img alt="logo"> 的 alt 文本仍被读作英文。这是因为：
- 浏览器按元素自身的
lang属性决定标点宽度、连字规则、字体回退链 - 屏幕阅读器逐个读取元素，不查父级
lang -
<title>、<meta name="description">等文档级元信息完全不继承<html>的lang
实操建议：
- 所有含文本的语义化标签（
<h1>、<p>、<section>、<article>、<footer>）都加lang，值与当前语言包一致 - 已有
lang的特殊元素（如<pre lang="bash">、<code lang="sql">）切换语言时保留原值，这是多语言混排的合法场景 -
<script>和<style>内部不要写lang，它们不参与文本渲染，设了也白设
data-i18n 必须覆盖所有可翻译属性，不只是 textContent
只给 <button>提交</button> 加 data-i18n="btn_submit"，但漏掉 placeholder 或 aria-label，会导致输入框提示始终是英文，辅助技术播报内容错位。
立即学习“前端免费学习笔记（深入）”；
常见错误现象：
- 表单
<input placeholder="Search...">切换语言后仍是英文 -
<img alt="user avatar">的替代文本没更新，影响无障碍访问 -
<label for="email">Email</label>文字翻了，但for没同步到对应id，导致点击 label 失效
实操建议：
- 每个要翻译的元素至少有一个基础
data-i18n键；含placeholder就额外加data-i18n-placeholder；同理data-i18n-title、data-i18n-alt -
value属性一般不翻译（属于用户输入数据），跳过处理 - 含 HTML 结构的文案（如“请阅读使用条款”）必须用
innerHTML替换，且语言包里对应值要是可信纯 HTML 片段，否则有 XSS 风险
动态插入的 DOM 必须手动触发翻译，不会自动监听
AJAX 加载的弹窗、表格行、懒加载模块插入后，如果没调用翻译函数，里面的 data-i18n 标记就只是字符串，不会变成对应语言文本。
使用场景：
- 点击按钮打开的 modal，内部
<h2 data-i18n="modal_title">不会自动更新 - 分页表格每页 AJAX 获取新行，新
<tr>里的data-i18n保持原始键名 - Web Component 自定义元素内部模板，首次渲染后未触发翻译逻辑
实操建议：
- 所有动态插入操作完成后，立即调用你的翻译函数（如
i18n.translate(el)），传入新节点或其父容器 - 不要依赖 MutationObserver 全局监听——开销大、易漏、难调试；精准控制插入点更可靠
- 若用 lit-html 或 React，需在组件挂载/更新后手动调用，框架本身不感知
data-i18n
语言包加载必须用 fetch + try/catch，且校验 response.ok 和 content-type
把语言包硬编码进 JS 文件，或用老式 XMLHttpRequest，很容易在 404、MIME 类型错误（如返回 text/plain）时静默失败，页面部分文案留空却无任何报错。
参数差异与兼容性影响：
- 路径必须统一为
./locales/${lang}.json，例如./locales/zh-HK.json、./locales/en-US.json - fallback 顺序必须是：先试完整 BCP 47 码（
zh-HK），再截主语言（zh），最后退到默认语言（en） - 服务器返回 JSON 时，HTTP
Content-Type必须是application/json，否则response.json()会抛错
实操建议：
- 加载逻辑外层包
try/catch，内部检查response.ok和response.headers.get('content-type') - 语言包结构必须扁平，所有语言文件字段完全对齐；某语言暂未翻译也要保留键，设为空字符串：
"btn_submit": ""，否则查不到 key 就留白 - 避免内联 JSON 或构建时注入——体积膨胀、无法热更新、CDN 缓存失效
最容易被忽略的是：lang 属性不是装饰，它是浏览器排版和辅助技术的行为开关；而 data-i18n 不是锦上添花的标记，它是翻译引擎的唯一指令入口——漏一个，就有一处不可访问、不可 SEO、不可正确渲染。
