probeo

How to fix lang and xml:lang that disagree?

html-xml-lang-mismatch page

The issue

A page that declares two languages leaves assistive technology to pick one. Depending on which attribute it reads, a screen reader may use the wrong pronunciation for the whole page, and the result can differ between tools reading the same page.

The cause is an <html> element carrying both lang and xml:lang, with values that name different languages. It usually comes from an old XHTML template whose xml:lang was never updated when lang was. WCAG 3.1.1 requires the page’s language to be identifiable by software, which a contradiction undermines.

Scope

Only the <html> element is checked, and only when it has non-empty lang and xml:lang both. Their primary subtags, the part before the first hyphen or underscore, are compared case-insensitively. en and en-US agree; en and de don’t.

How to check you have it

  • In probeo: the page reports html-xml-lang-mismatch, “HTML elements with lang and xml:lang must have the same base language”, with moderate impact.
  • By hand: view the page source and read the opening <html> tag. If it has both lang and xml:lang, they should name the same language.
  • With a tool: axe DevTools reports the same rule by the same name.

The fix

Make xml:lang name the same language as lang, or remove xml:lang.

An HTML page needs only lang. xml:lang matters for documents served as XML; if the site isn’t, removing it is the simpler fix and stops the two drifting apart again.

<html lang="de">

Done when: the <html> element declares one language, or two attributes that agree, and the check above comes back clean.

Do not

  • Do not fix only xml:lang and leave the template able to write a different value next time.
  • Do not remove lang and keep xml:lang.

FAQ

Do regions have to match too?

No. Only the primary language is compared, so lang="en-US" with xml:lang="en-GB" passes.

Why would a page have both?

Templates written for XHTML set both. Many still do, out of habit, long after the site stopped serving XML.

Does this matter if the page is otherwise fine?

The contradiction affects the whole page, since it is the page’s declared language. It is one attribute to fix.

Which product detects this

Probeo checks this on every page of your site as part of Site Clarity. This page explains one instance; the product tells you every page that has it.