Rome useValidLang 规则详解：校验 `html` 标签 `lang` 属性的 ISO 语言与地区代码-北京尧图网络

开发工具CLILint格式化静态分析代码质量构建工具【免费下载链接】toolsUnified developer tools for JavaScript, TypeScript, and the web项目地址https://gitcode.com/gh_mirrors/to/tools点击查看免费下载本篇技术指南围绕 Rome现 Biome 前身的 a11y 无障碍 lint 规则useValidLang展开该规则自 v12.0.0 起成为 Rome 的推荐recommended规则用于确保html元素上传递给lang属性的值是一个合法的 ISO 语言和/或国家地区代码。读完本文你将掌握该规则的触发条件、诊断信息含义、底层校验算法、ISO 数据来源以及如何在rome.json中开启、关闭或调整其严重级别让无障碍检查真正落地到你的 JSX/TSX 项目中。规则定位什么是 useValidLanguseValidLang是 Rome 无障碍a11y规则组中的一条规则其官方定义是Ensure that the attribute passed to thelangattribute is a correct ISO language and/or country.确保传给lang属性的值是正确的 ISO 语言和/或国家代码。在规则实现中通过declare_rule!宏声明的元信息明确了它的身份pub(crate) UseValidLang { version: 12.0.0, name: useValidLang, recommended: true, }version: 12.0.0规则自该版本起引入recommended: true属于推荐规则默认启用并在默认情况下以error严重级别输出诊断。在规则组的归属上useValidLang位于AriaAnalyzers类别的a11y分组下见 aria_analyzers.rs其完整的规则键为lint/a11y/useValidLang。为什么需要这条规则lang属性用于声明页面内容的主要语言屏幕阅读器、翻译工具与搜索引擎依赖它来正确发音与理解内容。如果lang值拼写错误或使用了不存在的语言代码无障碍辅助技术将无法正确解析页面语言这也是它被归入 a11y 规则组的根本原因。触发条件与错误示例Rome 的文档useValidLang.md给出了三类典型的无效写法以下逐一说明。无效示例一语言代码完全非法html langlorem /lorem既不是任何 ISO 639 语言代码也不是合法的地区代码。运行检查后Rome 会在lang属性值的位置高亮并输出如下诊断文档与测试快照中均为lint/a11y/useValidLanga11y/useValidLang.js:1:12 lint/a11y/useValidLang ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ✖ Provide a valid value for the lang attribute. 1 │ html langlorem / │ ^^^^^^^ ℹ Some of valid languages: - ab - aa - af - sq - am - ar - an - hy - as - ay - az - ba - eu - bn - dz无效示例二语言合法但地区代码非法html langen-babab /en是合法语言代码但babab并不是一个合法的 ISO 3166-1 国家/地区代码。此时诊断会提示Some of valid countries:部分合法国家/地区代码列表✖ Provide a valid value for the lang attribute. 1 │ html langen-babab / │ ^^^^^^^^^^ ℹ Some of valid countries: - AF - AL - DZ - AS - AD - AO - AI - AQ - AG - AR - AM - AW - AU - AT - AZ无效示例三语言-国家格式合法但存在多余段html langen-GB-typo /en-GB是合法组合但-typo作为第三个段是多余的。这类写法同样会触发诊断但因为没有明确命中语言不合法或国家不合法分类诊断不再附带候选列表仅输出核心错误信息✖ Provide a valid value for the lang attribute. 1 │ html langen-GB-typo / │ ^^^^^^^^^^^^有效示例大小写敏感的非 html 元素不检查Html langen-babab /注意这里元素名是Html首字母大写与html不相等。从规则实现可以看到规则的第一个前提就是元素名必须精确等于htmllet element_text node.name().ok()?.as_jsx_name()?.value_token().ok()?; if element_text.text_trimmed() html {因此自定义组件Html ... /不会被检查——规则的适用范围被严格限定在原生html根元素上。底层校验算法源码级解析useValidLang的核心校验逻辑位于 use_valid_lang.rs 的run方法中整体流程可以拆解为四步第一步定位目标元素与属性。规则以AriaAnyJsxElement为查询类型type Query AriaAnyJsxElement先确认元素名是html再通过node.find_attribute_by_name(lang)查找lang属性并经由initializer()与as_static_value()提取其静态字符串值。第二步按-拆分取值。关键代码是attribute_text.split(-)将lang值切分为若干段。随后用模式匹配处理两种主要形态let mut split_value attribute_text.split(-); match (split_value.next(), split_value.next()) { (Some(language), Some(country)) { ... } (Some(language), None) { ... } _ {} }第三步分类校验。规则内部定义了三种无效类型InvalidKindLanguage、Country、Value。形如语言-国家如en-GB依次校验语言段和国家段若两者都合法但split_value.next()还能取出第三段如en-GB-typo则判定为InvalidKind::Value形如语言如en只校验语言段其他形态如空值直接跳过不产生诊断。语言与国家分别通过ctx.is_valid_iso_language(language)与ctx.is_valid_iso_country(country)判定这两个方法由 AriaServices 提供最终委托给rome_ariacratepub fn is_valid_country(country: str) - bool { IsoCountries::from_str(country).is_ok() } pub fn is_valid_language(language: str) - bool { IsoLanguages::from_str(language).is_ok() }见 iso.rs第四步生成诊断。diagnostic方法use_valid_lang.rs#L99-L131统一输出错误信息Provide a valid value for the lang attribute.并根据invalid_kind决定是否附带候选列表InvalidKind::Language { let languages ctx.iso_language_list(); let languages if languages.len() 15 { languages[..15] } else { languages }; diagnostic.footer_list(Some of valid languages:, languages) } InvalidKind::Country { /* 同理提示 Some of valid countries: */ } InvalidKind::Value diagnostic,可以看到候选列表最多展示前 15 个合法值用于引导开发者快速参考。ISO 数据来源语言与地区代码表规则校验所依赖的 ISO 数据集中在rome_aria_metadatacrate 中定义于 lib.rsISO_LANGUAGES150 个合法 ISO 语言代码全部为小写包含zh、zh-Hans、zh-Hant、en、de、fr、es等常见值也保留了一些历史代码如iw希伯来语旧码、in印尼语旧码ISO_COUNTRIES233 个合法 ISO 3166-1 国家/地区代码全部为大写如AF、CN、GB、US、HK、TW等。从数据形态可以推断该规则对语言段与国家段是大小写敏感的精确匹配——en-gb小写国家不会通过国家校验EN大写语言也不会通过语言校验。因此推荐始终按规范书写语言小写、国家大写例如langen-GB、langzh-Hans、langzh-Hant-TW这类多段格式。这也解释了为何有效示例中langen-babab只报国家不合法——语言段en本身通过了校验。在 Rome 中配置 useValidLang由于useValidLang是推荐规则它默认随 linter 启用并生效。你可以通过rome.json显式管理它的行为完整配置说明见 linter 文档。保持默认启用在rome.json中开启linter并启用推荐规则集即可{ linter: { enabled: true, rules: { recommended: true } } }仓库根目录的 rome.json 自身即采用了这一推荐规则集配置。关闭规则将规则值设为off{ linter: { enabled: true, rules: { a11y: { useValidLang: off } } } }调整严重级别如果你正在重构、希望先以警告形式观察而非阻断 CI可将其设为warn{ linter: { enabled: true, rules: { a11y: { useValidLang: warn } } } }命令行运行在项目目录执行rome check ./src即可对整个src目录执行 lint 检查含格式与导入整理取决于配置。useValidLang的诊断会以lint/a11y/useValidLang的规则键呈现。由于该规则没有可配置项源码中type Options ()见 use_valid_lang.rs#L53因此无需像noCommentText等带选项的规则那样传options对象。临时忽略规则若个别行确实需要豁免可使用 Rome 的 suppression 注释格式如下详见 linter 文档的 Ignoring Code 一节// rome-ignore lint/a11y/useValidLang: 说明忽略原因 html langcustom-value /测试与验证快照测试佐证Rome 为useValidLang配备了规范的快照测试。测试输入位于 crates/rome_js_analyze/tests/specs/a11y/useValidLang/invalid.jsx由 spec_tests.rs 驱动覆盖了三种无效形态let a html langlorem /; let a html langen-babab /; let a html langen-GB-something /;对应快照 invalid.jsx.snap 逐一断言了三条诊断第一条附带语言候选列表第二条附带国家候选列表第三条多余段无候选列表。这与文档示例及上文对InvalidKind三种分支的分析完全一致形成了文档 → 实现 → 测试的闭环验证。实践建议语言段小写、国家段大写langen、langen-GB、langzh-Hans都是合规写法en-gb、EN会因大小写不匹配被标记。避免多余段en-GB-typo这类超出语言-国家两段的结构会被判定为非法。只作用于原生html元素自定义组件如Html /不受该规则约束若你的项目使用组件封装页面根元素需自行在组件内层使用原生html标签以继续获得检查。CI 集成保持推荐规则的error级别可在 CI 中尽早拦截无效的lang声明从源头保障页面语言信息的正确性与无障碍体验。相关链接Rome Linter 使用指南与规则配置含禁用规则与规则选项说明规则实现源码AriaServices 服务层ISO 校验函数ISO 语言与国家代码表规则测试快照赞分享开发工具CLILint格式化静态分析代码质量构建工具【免费下载链接】toolsUnified developer tools for JavaScript, TypeScript, and the web项目地址https://gitcode.com/gh_mirrors/to/tools点击查看免费下载相关推荐PentestGPT 上手指南从 Docker 部署到跑通第一次 AI 渗透测试PentestGPT 上手指南从 Docker 部署到跑通第一次 AI 渗透测试 PentestGPT 是一个由大语言模型驱动的自动化渗透测试框架给它一个目开发工具CLILint格式化静态分析代码质量构建工具Biome Markdown 规则 useFencedCodeLanguage 详解强制围栏代码块声明语言标签Biome Markdown 规则 useFencedCodeLanguage 详解强制围栏代码块声明语言标签导读 useFencedCodeLanguag开发工具Lint格式化静态分析代码质量前端DAKeyboardControl实战指南3种方法轻松处理键盘遮挡问题DAKeyboardControl实战指南3种方法轻松处理键盘遮挡问题还在为iOS开发中的键盘遮挡问题烦恼吗本文将为您介绍一款强大的开源工具——DA开发工具CLILint格式化静态分析代码质量构建工具上一篇Embla Carousel交互设计原则下一篇终极指南如何快速上手pi05_libero_base模型开启视觉-语言-动作机器人开发创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Rome useValidLang 规则详解：校验 `html` 标签 `lang` 属性的 ISO 语言与地区代码

相关推荐

MATLAB ode45隔震-锁榫系统地震响应分段仿真与参数扫参

基于Mahout的协同过滤电影推荐系统实战：数据清洗、算法选型与效果评估

2026数据治理平台选型指南：AI原生能力分化与DataFormula、WeData对比

更多资讯

uni-app x Worker 多线程开发指南：uni.createWorker 完整 API 解析与跨端实践

奥的斯ACD2 MR电梯GECB与OVF变频器调试参数及井道自学习故障排查

VuePress 主题继承（Theme Inheritance）实战指南：从 extend 配置到 @theme / @parent-theme 别名机制

Lostlife2.0整合LLama-Factory：从LoRA微调到NPC智能对话实践

VuePress 代码片段导入指南：`＜＜＜` 语法、`region` 区域提取与行高亮机制深度解析

BetterNCM Installer：网易云音乐插件管理器的安装与使用指南

今日更新

深入解析Transformer多头注意力机制与工程优化

OpenClaw 的 Skills 跑学习任务，模型通道改到 TaoToken 通道行不行？

ChatGPT报错Oops, an error occurred! 全链路排查指南

本周精选

深入解析Transformer多头注意力机制与工程优化

OpenClaw 的 Skills 跑学习任务，模型通道改到 TaoToken 通道行不行？

ChatGPT报错Oops, an error occurred! 全链路排查指南

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？