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

Rule ID: html-xml-lang-mismatch
Ruleset: axe-core 4.5
User Impact: Moderate
Guidelines: WCAG 2.1 (A), WCAG 2.0 (A)

Need accessibility training?

Deque University offers an extensive curriculum of self-guided online courses for every skillset and experience level.

Compliance Data & Impact

User Impact

Moderate
▼
Minor
Critical

Disabilities Affected

  • Blind
  • Deafblind
  • Cognitive

Standard(s)

  • WCAG 2.1 (A)
  • WCAG 2.0 (A)

WCAG Success Criteria [WCAG 2.1 (A)]

  • 3.1.1: MUST: Language of Page

WCAG Success Criteria [WCAG 2.0 (A)]

  • 3.1.1: MUST: Language of Page

How to Fix the Problem

Add a lang attribute value to the html element (e.g. <html lang="en">) indicating the primary document language.

If required, duplicate the value of the lang attribute as the value of the xml:lang attribute on the html element.

Remember to set the lang attribute value in the opening html element and spell the value correctly. For example, if the primary language of a document is English, specify the language as: 

<html lang="en">
  <!--document head and body-->
</html>

Language value codes include some dialects such as "en-US" to differentiate American English from UK English< or "fr-CA" to differentiate Canadian French from European French. You can find a list of language and dialect codes on the ISO Codes for the Representation of Names of Languages web page.

In the event of a document containing multiple languages, specify language values as required: 

<p>Text in one language <span lang="es">text in another language</span></p>

Be sure to specify languages written right-to-left using the dir attribute: 

<p lang="ar" dir="rtl">Arabic text here</p>

Conversely, you may also specify left-to-right languages via the dir="ltr" attribute value.

Why it Matters

When configuring a screen reader, users select a default language. If the language of a webpage is not specified, the screen reader assumes the default language set by the user. Multiple languages are an issue for users who speak and access websites in multiple languages. It is essential to specify a default language and ensure that it is valid for screen readers to function correctly.

Screen readers use different sound libraries for each language, based on the pronunciation and characteristics of that language. Screen readers can switch between language libraries easily, but only if documents specify which language(s) should to read. If the language is not specified, screen readers read documents in the user's default language, resulting in garbled language. It can be challenging to understand anything when screen readers are using the wrong language library.

Rule Description

The HTML document must contain a valid lang attribute or must correspond to a valid lang code for multilingual screen reader users who may prefer a language other than the default. The xml:lang attribute value, if included on the html element, must duplicate the value of the lang exactly.

The Algorithm (in simple terms)

Ensures every HTML document has a lang attribute with a valid value and, if present, the xml:lang value duplicates the lang value.

Resources

Deque University Course Pages (subscription required)

Contribute to axe-core on GitHub

Other Resources

You may also want to check out these other resources.

Was this information helpful?

You have already given your feedback, thank you..

Your response was as follows:

Was this information helpful?
Date/Time feedback was submitted: