Accessibility Insights

Back to Info and Examples for Accessibility Insights for Web

html-xml-lang-mismatch

The lang and xml:lang attributes of an element must have the same value.

Why it matters

When a web page’s primary language is programmatically identified, browsers and assistive technologies can render the text more accurately; screen readers can use the correct pronunciation; visual browsers can display the correct characters; and media players can show captions correctly. All users find it easier to understand the page’s content.

All HTML web pages must have a lang attribute on the <html> element and additional lang attributes on any elements whose content is in a different language. XHTML web pages and polyglot pages must also provide xml:lang attributes on those same elements.

When a single element has both lang and xml:lang attributes, the two values must match exactly. When the two attributes have different values, the user experience is unpredictable.

How to fix

For XHTML 1.x pages, or polyglot pages served as text/html:

  1. Use both the lang attribute and the xml:lang attribute each time you specify the language.
  2. Provide identical values for both attributes.

Example

 

Fail

The content of a web page is written primarily in Spanish. The <html> element's lang attribute correctly identifies the primary language as Spanish, but its xml:lang attribute identifies it as English.
<html lang="es" xml:lang="en">
 

Pass

Both the lang attribute and the xml:lang attribute correctly identify the primary language of the page as Spanish. Screen reader users find the content easier to understand because it's pronounced correctly.
<html lang="es" xml:lang="es">

About this rule

This rule passes if:

  • Lang and xml:lang attributes have identical values

More examples

Understanding Success Criterion 3.1.1: Language of Page

xml:lang in XML document schemas