前端国际化必须显式标记所有可翻译属性（如placeholder、title、alt、aria-label），统一用data-i18n及其变体（如data-i18n-placeholder）覆盖；lang属性需逐元素设置而非继承；语言包须遵循BCP 47命名、扁平结构、完整键对齐；动态插入DOM后必须手动触发翻译。
data-i18n标记必须覆盖所有可翻译属性，不只是textContent
只给加data-i18n="btn_submit"，但漏掉placeholder、title、alt或aria-label，是翻车最频繁的现场。表单输入框提示不换、图片替代文本卡在英文、屏幕阅读器播报错位，全因这些属性不会被textContent更新触达。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 每个要翻译的元素至少有一个基础
data-i18n键；含placeholder就额外加data-i18n-placeholder；同理data-i18n-title、data-i18n-alt -
value属性一般不翻译（属于用户输入数据），跳过处理；但label文字必须标记，且for属性要与对应id严格一致，否则点击失效 - 含HTML结构的文案（如“请阅读使用条款”）必须用
innerHTML替换，且语言包里对应值要是可信纯HTML片段——否则有XSS风险 - 别在
<script>、<style>、<pre>内部加data-i18n，这些节点不参与渲染，JS替换无效
lang属性必须显式设在每个语义化容器上，不能只靠继承
只改document.documentElement.lang = 'zh-HK'，页面视觉上像换了语言，但浏览器和屏幕阅读器根本没反应：顿号按英文间距渲染、<pre lang="bash">被中文字体覆盖、<img alt="logo">仍读作英文。这是因为浏览器和辅助技术严格按**每个元素自身的lang属性**决定行为，不是继承来的。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 所有含文本的语义化标签（
<h1>、<p>、<section>、<footer>等）都应显式加lang，值与当前语言包一致 - 已有
lang的特殊元素（如<pre lang="bash">、<code lang="sql">）切换语言时保留原值——这是合法的多语言混排，不是bug -
<title>、<meta name="description">等文档级元信息完全不继承<html>的lang，必须单独更新 - 避免在
<script>或<style>里写lang，它们不参与文本渲染，设了也白设
JSON语言包加载与结构必须严格遵循BCP 47和扁平对齐
把语言包硬编码进JS、或用XMLHttpRequest忽略MIME类型校验，会导致静默失败：服务器返回text/plain而非application/json，fetch可能不报错但response.json()抛异常；某语言文件缺一个键，整个页面就留白——因为查不到key就返回undefined。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 语言包路径统一为
./locales/${lang}.json，例如./locales/zh-Hans.json、./locales/en-US.json；BCP 47命名必须准确，zh_CN或chinese会被忽略 - 结构必须扁平、键名严格一致：所有文件字段完全对齐，某语言暂未翻译也要保留键，设为空字符串：
"btn_submit": "" - 加载必须用
fetch()，外层包try/catch，内部检查response.ok和response.headers.get('content-type')?.includes('application/json') - fallback顺序必须是：先试完整码（如
zh-HK），再截主语言（zh），最后退到默认语言（如en）
动态DOM插入后必须手动触发翻译，不会自动监听
AJAX加载的弹窗、分页表格新行、懒加载模块插入后，里面的data-i18n标记只是字符串，不会变成对应语言文本。用户点开modal看到modal_title原始键名，不是“登录成功”，这就是典型遗漏。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 任何动态插入的DOM（
appendChild、innerHTML、insertAdjacentHTML）插入后，必须立即调用翻译函数遍历其子树 - 不要依赖MutationObserver自动监听——它无法区分哪些节点是真实需翻译的，容易误触或漏触；明确在插入后调用更可控
- 第三方组件（如日期选择器）若含内建文案，需在其初始化后手动同步语言，不能指望全局翻译函数覆盖
- 切换语言前用
getComputedStyle记录滚动位置，更新完DOM后用window.scrollTo()恢复，否则页面会跳回顶部
