data-i18n默认仅更新textContent，需显式使用data-i18n-placeholder等后缀覆盖placeholder/title/alt等属性；lang属性须逐元素设置以保障可访问性与渲染正确性；语言包须扁平结构并带fallback加载机制。
data-i18n 标记必须覆盖所有可翻译属性，不只是 textContent
只给 <h1 data-i18n="home.title"></h1> 加属性，但漏掉 <input placeholder="Search"> 的 placeholder，切换语言后输入框提示仍是英文——这是最常被忽略的硬伤。
浏览器不会自动把 data-i18n 映射到所有属性；它默认只更新 textContent。要改 placeholder、title、alt、aria-label，必须显式加对应后缀：
data-i18n-placeholder="search.hint"data-i18n-title="btn.save.tooltip"data-i18n-alt="logo.alt_text"data-i18n-aria-label="nav.menu"
value 属性一般不翻译（属于用户输入数据），但 <button></button> 和 <input type="submit"> 的显示文案建议统一用 textContent 更新，避免意外提交非翻译值。
lang 属性必须显式设在每个语义化容器上，不是继承来的
只执行 document.documentElement.lang = 'zh-Hans'，页面文字可能变了，但屏幕阅读器仍按英文朗读，中文顿号间距错乱，<pre class="brush:php;toolbar:false;" lang="bash"></code> 里的代码字体被中文字体覆盖——因为浏览器和辅助技术**按每个元素自身的 <code>lang</code> 属性**决定行为。</p><p><span>立即学习</span>“<a href="https://pan.quark.cn/s/cb6835dc7db1" style="text-decoration: underline !important; color: blue; font-weight: bolder;" rel="nofollow" target="_blank">前端免费学习笔记（深入）</a>”；</p>
<p>初始化时，所有含文本的语义化标签都应显式写 <code>lang</code>：</p>
<ul>
<li><code><h1 lang="zh-Hans"></code></li>
<li><code><p lang="zh-Hans"></code></li>
<li><code><section lang="zh-Hans"></code></li>
</ul>
<p>已有明确多语言意图的元素（如 <code><pre class="brush:php;toolbar:false;" lang="bash"></code>、<code><code lang="sql"></code>）切换语言时**不能覆盖**其 <code>lang</code> 值，这是合法混排场景，不是 bug。</p>
<H3>JSON 语言包结构必须扁平、键名对齐、加载带 fallback</H3>
<p>把所有翻译塞进一个大对象里，或让 <code>en-US.json</code> 有 <code>"btn_submit"</code> 而 <code>zh-CN.json</code> 缺这个键，会导致查不到就留白——JS 不报错，只静默失败。</p><div class="aritcle_card flexRow">
<div class="artcardd flexRow">
<a class="aritcle_card_img" href="/xiazai/skill10828" title="财经HTML高端海报生成"><img
src="https://img.php.cn/upload/skill/001/246/273/6adaf20dbae7c507.jpg" alt="财经HTML高端海报生成" ></a>
<div class="aritcle_card_info flexColumn">
<a href="/xiazai/skill10828" title="财经HTML高端海报生成">财经HTML高端海报生成</a>
<p>复杂得财经如何变成清晰，适合手机看的海报？如何加上你的IP</p>
</div>
<a href="/xiazai/skill10828" title="财经HTML高端海报生成" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span> </a>
</div>
</div>
<p>正确结构是每个语言一个文件，路径统一为 <code>./locales/${lang}.json</code>，内容全为顶层键值对：</p>
<pre class="brush:php;toolbar:false;">{
"nav_home": "首页",
"form_submit": "提交",
"search_hint": "搜索商品..."
}</pre>
<p>加载逻辑必须带 fallback 链：</p>
<ul>
<li>先试完整码（如 <code>zh-HK）
zh）en-US）fetch 时务必检查 response.ok 和 response.headers.get('content-type')，HTTP 返回 text/plain 或 404 时会静默失败。
动态插入的 DOM 必须手动触发翻译，不会自动监听
AJAX 加载的弹窗、分页表格新行、懒加载模块插入后，里面的 data-i18n 仍是原始键名字符串——DOM 插入 ≠ 自动翻译。
插入后必须立即调用翻译函数，例如：
const modal = document.createElement('div');
modal.innerHTML = '<h2 data-i18n="modal.title"></h2>';
document.body.appendChild(modal);
translateElement(modal); // 手动触发
别依赖 MutationObserver：它无法区分“是新插入的待翻译节点”还是“已翻译完的节点”，且无法处理 innerHTML 内部的子节点。
最容易被忽略的点是：lang 属性和 data-i18n 是两套独立系统，必须同步更新；任何一方滞后，都会导致可访问性、SEO、字体渲染、标点规则全部错位——这不是样式问题，是语义断裂。
