When both lang and xml:lang attributes are present on the <html> element, they must identify the same language to ensure accessibility conformance. If these attributes conflict, assistive technologies and other software cannot reliably determine which language rules to apply.
This requirement exists to prevent ambiguity in how a page’s language is interpreted by software.
Background: Why xml:lang Exists
The xml:lang attribute comes from XML-based document formats, such as XHTML. XHTML documents are served with an XML MIME type (such as application/xhtml+xml), which causes the browser to parse them using XML rules instead of HTML rules. In those contexts, xml:lang was the primary way to declare language.
Modern HTML documents served as text/html use the lang attribute, defined by HTML5. In these documents:
langis the authoritative language declarationxml:langis unnecessary and usually should not be included
However, legacy systems, CMS templates, and XHTML carryovers sometimes include both, which is where accessibility issues arise.
What This Rule Applies To
This rule applies only when both attributes are present on the same element:
lang(HTML language attribute)xml:lang(XML language attribute)
HTML itself does not require these attributes to match.
However, WCAG conformance does, because the page’s language must be programmatically determinable without ambiguity.
WCAG Relationship
WCAG 3.1.1 Language of Page (Level A)
The default human language of each web page must be programmatically determinable. “Programmatically determinable” means that software, including screen readers, validators, and accessibility testing tools, can reliably identify the language from markup, without guessing or resolving conflicts.
WCAG does not define precedence rules for conflicting language metadata. Instead, it requires authors to avoid conflicts entirely.
How to Fix the Problem
Declare the primary language using lang
Every HTML document must declare its primary language on the <html> element.
<html lang="en">
<!-- document head and body -->
</html>This alone is sufficient for modern HTML documents.
If xml:lang is present, match it exactly
If xml:lang is included (for example, due to legacy XHTML compatibility), it must duplicate the lang value exactly.
<html lang="en" xml:lang="en">
<!-- document head and body -->
</html>Important details:
- Language tags are case-insensitive, but
- Tools perform string comparisons
enanden-USare not the same value, even though both are valid
For accessibility conformance, the values must match exactly.
Using language variants
Regional or dialect variants may be used as long as both attributes use the same BCP 47 language tag.
<html lang="en-US" xml:lang="en-US">
<html lang="fr-CA" xml:lang="fr-CA">Handling multiple languages within a page
When content switches language, mark only the affected elements.
<p>
Text in one language
<span lang="es">texto en otro idioma</span>
</p>
Language values are inherited by child elements unless overridden.
Do not overuse lang for single foreign words or proper nouns that do not affect pronunciation.
Right-to-left languages
Language does not imply text direction. Direction must be declared separately.
<p lang="ar" dir="rtl">Arabic text here</p>Use dir="ltr" where direction needs to be explicitly reset.
Why Conflicts Are Dangerous
Different systems resolve language metadata differently:
- In HTML parsing, browsers prioritise l
ang - In XML/XHTML contexts,
xml:langmay be used instead - Assistive technologies, validators, and testing tools do not follow a single, consistent precedence rule
When lang and xml:lang differ, there is no reliable, cross-platform way for software to determine the intended language. This makes the page’s language ambiguous and breaks WCAG 3.1.1.
Why This Matters
Screen reader users configure a default language in their assistive technology. If a page’s language is missing or ambiguous:
- The wrong pronunciation rules may be applied
- Voice switching may fail
- Braille translation tables may be incorrect
- Output may become difficult or impossible to understand
Using an incorrect but present value (for example, lang="en" on a Spanish page) is often worse than omitting the attribute, because it forces the wrong language rules consistently.
Common Real-World Failure Patterns
lang="en"withxml:lang="fr"lang="en"withxml:lang="en-US"- CMS templates injecting
xml:langautomatically - XHTML headers copied into HTML5 documents
- Pages translated visually but not updated consistently in markup
These patterns are consistently flagged by modern accessibility testing tools.
Rule Description
The <html> element must contain a valid lang attribute. If an xml:lang attribute is also present on the same element, its value must match the lang value exactly to ensure the language is programmatically determinable.
How to Test
- Inspect the opening
<html>element - Confirm a valid lang attribute exists
- If
xml:langis present, verify it matcheslangexactly - Confirm the declared language matches the visible content
If the values differ, the rule fails.
Algorithm
- Check for a valid
langattribute - If
xml:langexists:- Compare values exactly
- Fail if they differ
- Pass if the language is unambiguous to software
Wrapping Up
In modern HTML, lang is all you need. But when xml:lang is present, consistency is mandatory. Conflicting language declarations make the page’s language ambiguous to software, breaking WCAG conformance even when both values appear correct. Declare the language once, and if you declare it twice, make sure both declarations say the same thing.
