lang属性写错会导致浏览器翻译按钮不出现、屏幕阅读器误读、:lang()样式失效、axe报严重错误；必须写在<html>标签上且值严格符合BCP 47，如zh-CN、zh-TW、zh-HK，禁用zh、cn、下划线等非法格式。

lang属性写错的典型错误现象

浏览器翻译按钮不出现、NVDA/VoiceOver 读成日语腔或乱码、:lang(zh) CSS 规则完全不生效、Chrome DevTools 的 Accessibility 面板标红“Missing language declaration”、axe 工具报“严重（Critical）”错误。

必须改在 <html> 标签上，且值要严格匹配 BCP 47

只改 <body lang="zh-CN"> 或用 JS 动态设 document.documentElement.lang = "zh" 都无效。浏览器和辅助技术只认初始 HTML 中 <html> 标签上的声明。

• ✅ 正确写法（仅这三种中文主流值）：lang="zh-CN"（简体大陆）、lang="zh-TW"（繁体台湾）、lang="zh-HK"（繁体港澳）
• ❌ 常见非法值：lang="zh"（太宽泛）、lang="cn"、lang="ch"、lang="zh_CN"（下划线非法）、lang="zh-china"（大小写混用+非标准子标签）
• ⚠️ 注意：值必须全小写、用短横线 - 分隔，不能有空格或引号内多余字符

动态页面（React/Vue/SSR）怎么避免“改了等于没改”

SPA 里只靠 JS 改 document.documentElement.lang，屏幕阅读器不会重载语音引擎，CSS :lang() 也不会重新匹配——因为 DOM 已解析完成。

anything-to-html

将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。

下载

• SSR 项目（如 Next.js、Nuxt）：语言值必须从路由或请求头注入模板，确保首屏 HTML 的 <html lang="xx-XX"> 就是正确的
• 静态站点（Hugo/Jekyll）：每个语言版本生成独立 HTML，lang 硬编码进基础模板
• 纯前端 SPA：语言切换时强制整页刷新（window.location.href = "/en/about"），或重写 document.documentElement.outerHTML（但 ARIA 缓存清不干净，慎用）
• 局部多语言内容（如英文引文、代码块）：必须显式加 lang，例如 <p lang="en">API</p>、<pre lang="bash">curl -X POST</pre>

修复后必须验证的三个关键点

改完不是就结束了。很多团队只检查文案是否替换，漏掉真正决定行为的底层信号。

立即学习“前端免费学习笔记（深入）”；

• 打开 DevTools → Elements 面板，确认 <html> 标签上 lang 属性存在且拼写准确（注意有没有空格、大小写、下划线）
• 运行 document.documentElement.lang，输出必须和你预期一致；再查 document.charset 是否为 "UTF-8"，两者必须同时正确
• 用 axe 浏览器插件或 Lighthouse 运行无障碍审计，确认 “Document has a valid language” 错误消失

真正容易被忽略的是：lang 和 charset 是耦合项，一个写错，另一个再准也没用；而回归测试如果只断言 DOM 文案、不查 document.documentElement.lang 和响应头的 Content-Type，等于绕过最常出问题的链路。