仅靠lang属性无法解决发音问题，因为它只指定语音引擎而不处理多音字、专有名词或外语借词的准确读音；<ruby>等语义标签必须配合正确lang才能被屏幕阅读器识别并朗读。
为什么只靠 lang 属性无法解决发音问题
很多团队误以为只要在 <html lang="zh-CN"> 里写对语言码，屏幕阅读器就能“自动读准”。现实是：它只决定用哪个语音引擎，不保证读对多音字、专有名词或外语借词。比如“行”在“银行”里读 xíng，但没标注时，VoiceOver 很可能读成 háng；又如“iPhone”被中文引擎强行按拼音读成“爱佛恩”，而非 /ˈaɪfoʊn/。
常见错误现象：
- 日语人名「佐藤」被中文引擎读作“zuǒ téng”，而非“さとう”
- 德语术语
Rechtsschutzversicherung在中文页面中无lang="de"标注，被当作乱码切音节 - 使用
<ruby>但未配lang，导致 iOS VoiceOver 忽略 ruby 内容，直接跳过整段
<ruby> 必须配合 lang 才生效
<ruby> 不是装饰性标签，它是为辅助技术提供结构化发音信息的语义容器。但它的作用前提是：父级或自身必须声明正确语言环境，否则屏幕阅读器不会激活 ruby 解析逻辑。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 中文拼音标注必须写
<ruby lang="zh-Hans">汉字<rp>(</rp><rt>hàn zì</rt><rp>)</rp></ruby>，不能省略lang="zh-Hans" - 日语振假名要同时声明外层和内部语言：
<p lang="ja"><ruby>東京<rp>(</rp><rt>とうきょう</rt><rp>)</rp></ruby></p> - 避免嵌套错位：不要把
<ruby>放在<div lang="en">里却不重设lang——这样 ruby 内容会被当成英文处理 - 注意兼容性：NVDA + Firefox 支持完整 ruby 朗读；iOS VoiceOver 需 iOS 16+ 且仅在
lang明确匹配时触发
局部外语内容必须显式声明 lang，哪怕只有一词
大型多语言站常有术语混排场景（如中文文档夹英文 API 名、法语引文、阿拉伯语地名），这些片段若不单独标注 lang，就会被根语言引擎“强译”，结果不是读错，就是跳过。
使用场景与参数差异：
- 代码块中的英文变量：
<code lang="en">useState</code>→ 触发英文 TTS，保留大小写与连字符逻辑 - 引用的西班牙语句子：
<blockquote lang="es">No hay mal que por bien no venga.</blockquote>→ 启用西班牙语断句与重音规则 - 缩略语首次出现：
<abbr lang="en" title="Application Programming Interface">API</abbr>→ AT 可读出全称，且不误判为中文拼音 - 禁止写
lang="bash"或lang="sql"：这些不是 BCP 47 语言码，应改用lang="en"或留空
动态切换语言时，document.documentElement.lang 和所有子节点 lang 必须同步更新
SPA 类站点（如 React/Vue 构建的管理后台）最容易在这里翻车：用户点「切换为日语」，JS 只改了 document.documentElement.lang = "ja-JP"，但页面已渲染的 <p lang="zh-CN">、<ruby> 等节点仍保持旧值。后果是：VoiceOver 继续用中文引擎读日文内容，ruby 被忽略，::lang(ja) CSS 不匹配。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 语言切换函数必须遍历并重置所有含
lang的元素：document.querySelectorAll('[lang]').forEach(el => el.lang = newLang) - 对
<ruby>特别小心：其内部<rt>是独立文本节点，需确保父<ruby>的lang已更新，否则<rt>仍被按旧语言解析 - 避免用 CSS class 模拟语言切换（如
.lang-zh）：辅助技术完全无视 class，只认lang属性 - 服务端渲染（SSR）站点更简单：每个语言路径返回完整 HTML，
<html lang="...">硬编码，无需 JS 补救
最易被忽略的一点：即使你把所有 lang 都更新了，如果页面里存在通过 innerHTML 动态插入的富文本（比如 CMS 编辑器输出），那些新插入的节点默认没有 lang，必须手动补上——否则它们会继承根语言，破坏局部多语上下文。
