Page must declare LANG attribute on the HTML element.
Description
A page read aloud in the wrong voice is confusing from the first word. Screen readers, braille displays, and translation tools choose pronunciation rules from the language declared on the html element; when that value is missing, empty, or malformed, assistive technology falls back to a default voice and mispronounces content. WCAG Success Criterion 3.1.1 makes this declaration a Level A requirement.
Valid values follow BCP 47, for example en, en-GB, or ru-Cyrl-BY. The audit reads the root element and reports a missing attribute, a blank value, an invalid tag, or a tag with more than three subtags, including underscore separators such as en_US. Setting the language correctly improves accessibility, helps browsers select fonts and hyphenation, and gives search engines a clearer signal about the primary language of the page.
Disabilities impacted
- Visual: Screen reader and braille display users depend on the declared language to select pronunciation and contraction rules; a missing or wrong value produces garbled output.
- Cognitive: Readers with dyslexia or language processing difficulties benefit from correct pronunciation and accurate translation, which reduce the effort needed to understand text.
- Screen reader: Assistive technology switches voices and dictionaries based on the root language; an invalid tag forces a default voice and mispronounces words throughout the page.
- Motor: Voice control and dictation users rely on language identification to load the right recognition grammar, improving command and text-entry accuracy.
Why it matters
Language metadata shapes whether people can consume content at all. Correct pronunciation and braille contraction rules – including region-specific vocabulary – lower cognitive load, improve comprehension for non-native readers, and make translated snippets more accurate in search results. That reliability also supports ADA and Section 508 obligations, reduces support complaints, and prevents the subtle exclusion that happens when an entire page sounds foreign to the technology meant to read it.
Coding problems and solutions
Common coding problems
- Missing attribute: The
htmlelement has nolangattribute at all, so assistive technology must guess the language. - Empty value: Attributes such as
lang=""or whitespace-only values are present but carry no usable information. - Incorrect separator: Values like
en_USuse an underscore instead of the required hyphen between subtags. - Non-tag value: Words such as
Englishorfoobarare written instead of a real language code. - Too many subtags: Tags such as
zh-Hant-TW-x-privatecontain four subtags and exceed the three-part limit applied by this audit. - Wrong element: The language is placed on
bodyor a wrapperdivwhile the roothtmlelement is left undeclared.
How to fix it
Declare the language on the root element
Add a lang attribute directly to html, using the language of the majority of the page content.
<!DOCTYPE html>
<html lang="en">
<head>
<title>Sample page</title>
</head>
<body>
<p>Content in English.</p>
</body>
</html><!DOCTYPE html>
<html>
<head>
<title>Sample page</title>
</head>
<body>
<p>Content in English.</p>
</body>
</html>Use valid BCP 47 syntax
Separate subtags with hyphens and use registered codes; grandfathered tags such as i-default are also accepted.
<html lang="en-GB">
<body>
<p>Content in British English.</p>
</body>
</html><html lang="en_GB">
<body>
<p>Content in British English.</p>
</body>
</html>Keep the tag within three subtags
Prefer a concise language, script, and region combination; extension subtags push the value past the limit enforced by this check.
<html lang="fr-FR">
<body>
<p>Contenu en français</p>
</body>
</html><html lang="fr-FR-x-private">
<body>
<p>Contenu en français</p>
</body>
</html>Mark passages in other languages
Keep the root language accurate and add lang on individual elements when a section switches language.
<html lang="en">
<body>
<p>Default English content.</p>
<p lang="fr">Bonjour, comment allez-vous ?</p>
</body>
</html><html lang="en">
<body>
<p>Default English content.</p>
<p>Bonjour, comment allez-vous ?</p>
</body>
</html>Keep the language in sync in client-side apps
When routes change the displayed language, update document.documentElement.lang rather than a nested element.
const setDocumentLanguage = (languageTag) => {
document.documentElement.lang = languageTag;
};
const renderRoute = (route) => {
setDocumentLanguage(route.languageTag);
render(route.component);
};const setDocumentLanguage = (languageTag) => {
document.body.setAttribute('lang', languageTag);
};Known Limitations
- Root element only: The audit inspects the document root exclusively; it does not validate
langattributes placed on nested elements or inline passages. - SPA route changes: Single-page apps that swap content without updating the root attribute after the initial scan are not rechecked by this rule.
- Iframes and shadow DOM: Embedded documents and shadow trees have separate roots and fall outside the scanned element.
- Tag validation approximation: Validity relies on
Intl.getCanonicalLocalesplus custom rules, so extension-heavy tags with four or more subtags are reported even when BCP 47 permits them. - Grandfathered exceptions: A fixed allowlist of grandfathered tags is accepted; uncommon legacy tags missing from that list may be flagged as invalid.
- Content mismatch: The check confirms the attribute exists and is well formed but cannot tell whether the declared language matches the text actually rendered on the page.
Resources
- WCAG: Understanding Language of Page explains the intent of Success Criterion 3.1.1.
- W3C: W3C HTML lang attribute definition describes valid values on the root element.
- MDN: MDN lang attribute guide covers practical usage and screen reader behaviour.
- WHATWG: WHATWG HTML standard defines language processing for documents.
- BCP 47: RFC 5646 specifies the complete tag syntax.
Rule
- Audit: accessibility
- Standard: WCAG
- Level: A
- Success Criteria: 3.1.1
- Rule ID:
html-lang-attr