必须用语义化标签打底、data-i18n锚定、lang属性精准控制三者协同，缺一不可；否则改文案、加模块、切rtl时将全面失效。
HTML结构本身不国际化，真正要做的，是让结构能稳定承载多语言内容——靠语义化打底、data-i18n锚定、lang属性精准控制，三者缺一不可。硬套框架或只改document.documentElement.lang，后面改文案、加新模块、切RTL语言时全得重来。
为什么必须用语义化标签打底，而不是靠 class 或 id 定位翻译？
靠class="header-title"或id="login-btn"找元素做翻译，等于把 DOM 查询逻辑和样式/设计强耦合。设计师删个 class、CSS 覆盖掉某个 class 名、JS 动态移除 class——翻译就失效。而header、main、article是标准 DOM 接口，浏览器和 JS 都认，不会被样式或脚本意外破坏。
-
document.querySelector('header')永远指向页眉区域，不管它有没有 class -
article天然适合包裹独立可翻译单元（如一篇新闻、一个表单区块），每个article可自带data-i18n，互不影响 - 多个
nav允许存在（比如全局导航 + 侧边栏导航），但main必须唯一——这是屏幕阅读器和 SEO 的硬约束，乱嵌套会导致翻译节点错位或跳过
data-i18n怎么加才不漏、不串、不崩？
data-i18n不是装饰性属性，它是翻译系统的“寻址指令”。加错位置、漏加、加在不该加的地方，都会导致文本不动、属性没更新、甚至 XSS。
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
- 只加在最终渲染为用户可见文本的元素上：
<h2 data-i18n="about.title"></h2>✔️；<script>...</script>、<pre class="brush:php;toolbar:false;">...</pre>、<style>...</style>❌（这些节点不参与文本渲染） - 属性类值需单独标记：
placeholder、title、alt不受data-i18n影响，得用data-i18n-placeholder、data-i18n-title、data-i18n-alt - 含 HTML 的文案（如“请阅读服务条款”）必须用
innerHTML替换，且语言包里对应键值必须是已过滤的可信 HTML 片段——直接插 raw 字符串等于开 XSS 后门 - 不要指望父容器自动透传：
<div data-i18n="form"> <label>邮箱</label><input> </div>→label和input的 placeholder 仍需各自加data-i18n，否则不翻
切换语言时，lang 属性为什么不能只动根节点？
document.documentElement.lang = 'ja' 只改了根节点，对页面里所有已有子元素的 lang 属性毫无影响。浏览器按每个节点自己的 lang 决定字体回退、标点间距、语音朗读方式——不是继承来的。
- 局部多语言内容（如引用日文原文的
<p lang="ja">...</p>）必须显式保留lang="ja"，不能被全局切换覆盖成lang="en" - 切换后要遍历并同步更新所有带
lang的元素：根节点设lang="zh-Hans"，同时把所有<blockquote lang="en"></blockquote>、<code lang="bash">等保持原值，仅更新无lang的普通文本容器 - 注意 BCP 47 格式：
zh-CN或chinese会被忽略，必须用zh-Hans（简体中文）、zh-Hant（繁体中文）、en-US等标准值
最易被忽略的点：语义结构和 data-i18n 是绑定关系，不是独立配置。新增一个 section 模块，如果忘了加 data-i18n，或者把它塞进没语义的 div 堆里，后续所有翻译逻辑都找不到它——这种漏项在多人协作或迭代中极难发现，直到上线后某条文案死活不翻才排查出来。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
