Rule ID: ace-meta-lang-mismatch

Check that lang and xml:lang attributes on the HTML element specify the same base language

WCAG 2.0 (A) - WCAG 2.2 (A) 3.1.1: Language of Page Blind Deafblind Cognitive User Impact

What This Rule Checks

When both lang and xml:lang attributes are present in the <html> element, their values must match. The lang attribute is used for HTML documents, while the xml:lang attribute is used for XML documents, including XHTML. If these attributes have different values, assistive technologies and browsers may get confused about which language to use, leading to incorrect pronunciation or interpretation of the content.

Who Is Affected

This issue primarily affects: Blind users, who rely entirely on screen readers or braille displays to navigate and interact with content; Deafblind users, who rely on braille displays and cannot access visual or auditory content; Cognitive users, who benefit from clear structure, simple language, and consistent navigation patterns.

Why This Matters

When lang and xml:lang specify different languages, assistive technologies must choose between conflicting instructions. This can cause the wrong pronunciation rules to be applied to the entire page.

How to Fix

Ensure both attributes are present in the <html> element and their values match.

For RTL languages, also include dir=”rtl” to indicate the correct text direction.

Use valid IETF BCP 47 language tags to specify the document’s primary language (e.g., lang=”en” and xml:lang=”en” for English, or lang=”ar” and xml:lang=”ar” for Arabic).

Code Examples

Incorrect Markup Solutions:

Code example

<!-- Mismatched lang and xml:lang -->
<html lang="en" xml:lang="fr">
  <body>
    English content here
  </body>
</html>

Copy

Correct Markup Solutions:

Code example

<!-- Matching lang and xml:lang -->
<html lang="en" xml:lang="en">
  <body>
    English content here
  </body>
</html>

Copy

Correct Markup Solutions:

Code example

<!-- Or omit xml:lang for HTML5 documents -->
<html lang="en">
  <body>
    English content here
  </body>
</html>

Copy

Common Mistakes to Avoid

Setting different languages in lang and xml:lang attributes.
Adding xml:lang to HTML5 documents where it’s unnecessary.
Copy-pasting from XHTML templates without updating both attributes.

Tip: Page-level metadata and settings affect the entire browsing experience. Language declarations, viewport settings, and page titles are foundational to accessibility and affect every user on every page load.

Related WCAG Criteria

• 3.1.1: Language of Page