Front-End-Checklist 无障碍规则实战lang 与 xml:lang 属性一致性WCAG 2.1 SC 3.1.1【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist导读本文基于开源仓库 Front-End-Checklist 中skills/html-xml-lang-mismatch/SKILL.md及其配套规则文档系统讲解html元素上lang与xml:lang属性必须保持一致这一无障碍规则。你将掌握三种文档类型标准 HTML5、XHTML、polyglot 混合文档各自的属性声明要求、BCP 47 语言标签的校验方法以及如何把该规则接入你团队的代码审查与自动化审计流程。规则概述同一元素上的两个语言属性必须完全一致当同一个元素上同时出现lang和xml:lang两个属性时它们的值必须完全相同。这条规则在 Front-End-Checklist 仓库中被归类为accessibility无障碍类别下的visual子类元数据中标注的优先级为medium中等、难度为beginner入门、预估耗时5 分钟见 规则内容文件 的 frontmatter。HTML Living Standard 与 W3C 的语言声明指南都将这两个属性的取值不一致视为对解析器和用户代理user agent发出的矛盾语言信号——同一份文档HTML 解析器读到的是一种语言XML 解析器读到的却是另一种语言。仓库中该规则有三个信息载体职责分工明确skills/html-xml-lang-mismatch/SKILL.mdAgent/LLM 可消费的技能指令文件包含 check / fix / explain / code review 四个阶段的提示词模板skills/html-xml-lang-mismatch/references/rule.md给人类开发者看的完整规则说明含代码示例、适用场景表格、最佳实践与验证方法packages/content/rules/en/accessibility/html-xml-lang-mismatch.mdx规则的结构化数据源frontmatter 中定义了 whyItMatters、prompts、sources、relatedRules 等字段供网站渲染与规则引擎消费。为什么这条规则重要屏幕阅读器会选错语音库屏幕阅读器使用lang属性来选择正确的语音配置voice profile和发音引擎。如果lang和xml:lang取值不一致基于 XML 的处理程序包括部分 EPUB 阅读器和较旧的辅助技术可能优先采用xml:lang的值导致实际朗读语言与页面意图不符。规则文档给出了一个典型场景法语文本被英语语音包朗读对法语盲人用户而言输出完全无法理解。解析器兼容性HTML 解析器使用langXML 解析器使用xml:langpolyglot 文档同时合法于 HTML 与 XML必须同时满足两者。翻译工具与拼写检查浏览器自动翻译功能依赖lang检测源语言拼写检查器也依据语言声明选用正确的词典规则。语言声明错误会连锁影响这些工具。WCAG 合规要求这条规则对应WCAG 2.1 SC 3.1.1Language of Page页面语言要求每个网页的默认人类语言可以通过编程方式确定。lang服务于 HTML 解析器xml:lang服务于 XML 解析器当文档必须同时以 HTML 和 XML 解析时polyglot两个属性必须同时存在且一致。不一致意味着文档的语言声明取决于谁在读它这正是无障碍合规审计必须拦截的问题。Check如何检查是否存在不一致按照 SKILL.md 中的 check 提示词检查流程分三步检查属性存在性检查html元素上是否同时存在lang和xml:lang比对取值若两者都存在确认其值完全一致——必须包含子标签subtags级别的比对en与en-US属于不匹配校验 BCP 47 合法性确认语言标签本身是合法的 BCP 47 语言标签如en、en-US、fr、zh-Hant。任何差异包括主语言标签不同、方言子标签不同、标签非法都应被标记为违规。Fix如何修复修复策略取决于文档类型值不一致将lang与xml:lang都更新为同一个合法的 BCP 47 语言代码且该代码必须匹配文档内容的主要语言标准 HTML5 文档以text/html提供直接移除xml:lang它在此场景下是多余的XHTML 或 polyglot 文档保留两个属性并确保它们完全一致。代码示例正确与错误的写法来自 references/rule.md 的完整示例!-- ✅ Correct HTML5 document: only lang needed -- !DOCTYPE html html langen !-- ✅ Correct polyglot/XHTML document: both present and identical -- html langfr xml:langfr !-- ❌ Incorrect: values differ -- html langen xml:langfr !-- ❌ Incorrect: dialect mismatch — en vs en-US -- html langen xml:langen-US !-- ❌ Incorrect: invalid language tag -- html langenglish注意最后一种情况english不是合法的 BCP 47 标签正确写法是en。方言子标签也必须一致——en-GB与en之间同样构成不匹配。什么时候该用哪个属性规则文档给出的决策表是这条规则最核心的实操依据文档类型langxml:lang标准 HTML5text/html必需不需要XHTMLapplication/xhtmlxml推荐必需Polyglot HTML同时合法于两种解析必需必需值相同判断一份文档是否属于 polyglot核心看它的 MIME 类型与DOCTYPE声明。现代前端项目绝大多数属于第一行标准 HTML5场景。最佳实践新 HTML5 项目只用lang在html上只写lang省略xml:lang保持同步如果出于兼容性考虑添加了xml:lang必须始终与lang保持一致子标签一致性若一个属性写了en-GB另一个也必须写en-GB不能简写为en以渲染结果为准规则文档的 Exceptions 部分提醒——在把静态代码异味当作阻断项之前先评估实际渲染体验交互时序、浏览器行为与辅助技术的实际输出往往决定问题严重程度。不是每个次要无障碍问题都值得同等的修复优先级应优先处理最直接阻碍感知、操作或理解的项同时避免为了满足规则而堆砌多余的标记或 ARIA能通过更简单的语义实现消除问题时就选择更简单的方案。源码级实践Front-End-Checklist 自身如何声明语言规则文档还给出了源码级最佳实践的实证。Front-End-Checklist 的 Web 应用是一个 Next.js 项目其根布局遵循标准 HTML5 只用lang的推荐做法apps/web/app/layout.tsx 中根html元素声明为html langen ...只包含lang属性没有xml:langapps/web/app/global-error.tsx 中全局错误页同样使用html langen contenteditable="false">【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考