html-xml-lang-mismatch
Match lang and xml:lang attributes
Screen readers use the lang attribute to select the correct voice profile and pronunciation engine. If lang and xml:lang disagree, XML-based processors (including some EPUB readers and older assistive technologies) may use xml:lang and get a different language than intended — causing text to be read aloud in the wrong language. For example, French text read with an English voice profile produces unintelligible output for French-speaking blind users.
Quick Reference
- If both
langandxml:langare present on<html>, their values must be identical xml:langis only needed for XHTML or polyglot documents (valid as both HTML and XML)- For standard HTML5 documents, only
langis required —xml:langis redundant - The primary language tag must be a valid BCP 47 language code (e.g.,
en,en-US,fr,zh-Hant) - Relates to WCAG 2.1 SC 3.1.1 (Language of Page)
Check
Inspect the <html> element for both lang and xml:lang attributes. If both are present, verify their values are identical (including subtags — en vs en-US is a mismatch). Also verify that the value is a valid BCP 47 language tag. Flag if the values differ in any way.
Fix
If lang and xml:lang are present but differ: update both to the same valid BCP 47 language code matching the primary language of the document content. If this is a standard HTML5 document (served as text/html), remove xml:lang — it is unnecessary. If this is XHTML or a polyglot document, keep both and ensure they are identical.