HTML lang Attribute
debt(d3/e1/b3/t5)
Closest to 'default linter catches the common case' (d3). The detection_hints list lighthouse, axe, wave, and webhint — all widely-used, commonly-run accessibility tools that flag missing lang on <html> as an automated check. These are not exotic specialist tools; axe and lighthouse in particular are default or near-default in many CI pipelines and browser devtools, placing this squarely at d3.
Closest to 'one-line patch or single-call swap' (e1). The quick_fix explicitly states: add lang='en' (or appropriate BCP 47 code) to the opening <html> tag — a single attribute addition on one element. Even correcting a wrong language value is a one-character-to-a-few-character edit.
Closest to 'localised tax' (b3). The fix lives in one place — the root <html> element — so it does not spread across the codebase. However, it is a persistent accessibility obligation on every HTML page produced (applies_to: web), meaning templating systems or CMS configurations may need to be checked. The reach is contained but not trivial, landing at b3.
Closest to 'notable trap (a documented gotcha most devs eventually learn)' (t5). The misconception field identifies a real, well-documented trap: developers assume lang only matters for non-English sites, so they omit it on English pages or set it incorrectly. The common_mistakes also highlight that setting the wrong language (e.g. lang='en' on a Polish page) is actively worse than omitting it, and that BCP 47 casing rules (en-GB, zh-Hant) trip up developers. These are known gotchas that most developers eventually learn, fitting t5.
Also Known As
TL;DR
Explanation
The lang attribute on the <html> element is one of the highest-impact, lowest-effort accessibility improvements. Screen readers (JAWS, NVDA, VoiceOver, TalkBack) use it to select the appropriate voice engine — without it, the reader uses its default language, producing incomprehensible pronunciation for content in another language. The value must be a valid BCP 47 language tag: 'en' for English, 'en-GB' for British English, 'fr' for French, 'de' for German, 'pl' for Polish. For multilingual pages, individual sections can override with lang on a specific element (<blockquote lang='fr'>) — this allows the screen reader to switch voice mid-page. WCAG 2.1 Success Criterion 3.1.1 (Language of Page) is Level A — the minimum accessibility conformance level. Missing lang is both a WCAG A failure and a Lighthouse accessibility score deduction.
Common Misconception
Why It Matters
Common Mistakes
- Omitting lang entirely — the most common mistake, fails WCAG 3.1.1 Level A.
- lang='en' on a non-English page — setting the wrong language is worse than omitting it; the screen reader pronounces every word with the wrong phonology.
- Using an invalid language tag (lang='english', lang='EN-us') — BCP 47 subtags are case-sensitive; the primary tag is lowercase, the region tag is uppercase (lang='en-GB', lang='zh-Hant').
- Setting lang on <body> instead of <html> — must be on the root <html> element per WCAG specification.
Avoid When
- Do not set lang to a language that doesn't match the page content — wrong lang is worse than missing lang for screen reader users.
When To Use
- Always — every HTML page must have lang on the <html> element.
- Add lang on specific elements when a section of the page is in a different language from the page default.
Code Examples
<!-- Missing lang — screen reader guesses language -->
<html>
<head><title>Strona główna</title></head>
<body>Witaj na naszej stronie...</body>
</html><!-- Correct lang on root html element -->
<html lang="pl">
<head><title>Strona główna</title></head>
<body>
Witaj na naszej stronie...
<!-- Inline language change for foreign-language quote -->
<blockquote lang="en">"To be or not to be"</blockquote>
</body>
</html>