Accessibility Rule: HTML elements with lang and xml:lang must have the same base language

About This Accessibility Rule

The lang attribute tells browsers and assistive technologies what language the content is written in. The xml:lang attribute serves the same purpose but comes from the XML/XHTML specification. When both attributes are present on the same element—most commonly the <html> element—they must agree on the base language. The “base language” is the primary language subtag (e.g., en in en-US or fr in fr-CA). If one attribute says en and the other says fr, assistive technologies receive conflicting information and cannot reliably determine how to process the content.

Who is affected

This issue primarily impacts screen reader users, including people who are blind, deafblind, or have cognitive disabilities. Screen readers maintain separate pronunciation libraries for each language. When they encounter a language declaration, they switch to the appropriate library so words are spoken with correct pronunciation and cadence. A mismatch between lang and xml:lang can cause the screen reader to select the wrong library or behave unpredictably, making the content difficult or impossible to understand.

Users who speak multiple languages and browse sites in different languages are especially vulnerable, as they rely on accurate language declarations to switch between language contexts.

Related WCAG success criteria

This rule relates to WCAG Success Criterion 3.1.1: Language of Page (Level A), which requires that the default human language of each web page can be programmatically determined. This criterion applies across WCAG 2.0, 2.1, and 2.2, as well as EN 301 549 and RGAA. When lang and xml:lang conflict, the programmatically determined language becomes ambiguous, violating this requirement.

How to fix it

Check the <html> element (and any other elements) for the presence of both lang and xml:lang attributes.
Ensure both attributes use the same base language. For example, if lang="en", then xml:lang must also start with en (e.g., en, en-US, or en-GB).
If you don’t need xml:lang, the simplest fix is to remove it entirely. The lang attribute alone is sufficient for HTML5 documents.
If you’re serving XHTML, both attributes may be required. In that case, keep them in sync.

You can find valid language codes on the ISO 639 language codes reference page. Common codes include en for English, fr for French, es for Spanish, de for German, and ar for Arabic.

Examples

Incorrect: mismatched base languages

The lang attribute specifies English, but xml:lang specifies French. This creates a conflict that confuses assistive technologies.

<html lang="en" xml:lang="fr">
  <head>
    <title>My Page</title>
  </head>
  <body>
    <p>Hello, world!</p>
  </body>
</html>

Correct: matching base languages

Both attributes specify English. The dialect subtag may differ, but the base language (en) is the same.

<html lang="en-US" xml:lang="en-GB">
  <head>
    <title>My Page</title>
  </head>
  <body>
    <p>Hello, world!</p>
  </body>
</html>

Correct: identical values

The simplest and most reliable approach—use the exact same value for both attributes.

<html lang="en" xml:lang="en">
  <head>
    <title>My Page</title>
  </head>
  <body>
    <p>Hello, world!</p>
  </body>
</html>

Correct: only `lang` attribute (HTML5)

In HTML5 documents, the xml:lang attribute is not required. Using lang alone avoids any possibility of a mismatch.

<html lang="en">
  <head>
    <title>My Page</title>
  </head>
  <body>
    <p>Hello, world!</p>
  </body>
</html>

Correct: specifying language on inline elements

When content in a different language appears within the page, use the lang attribute on the appropriate element. If you also use xml:lang, make sure they match.

<p>Welcome to our site. <span lang="es" xml:lang="es">Bienvenidos a nuestro sitio.</span></p>

For right-to-left languages, also include the dir attribute:

<p lang="ar" xml:lang="ar" dir="rtl">مرحبا بكم في موقعنا</p>

Learn more:

Deque Reference

Deque University - How To Fix

→

W3C Reference

WCAG 2.1 - Using the language attribute on the HTML element

→

Help us improve our guides

Was this guide helpful?

Detect accessibility issues automatically

Rocket Validator scans thousands of pages with Axe Core and the W3C Validator, finding accessibility issues across your entire site.

Start Free Trial See Pricing

HTML elements with lang and xml:lang must have the same base language