The page language needs a valid language tag

• Rule: axe/html-lang-valid
• Checks: <html> element must have a valid value for the lang attribute
• WCAG: 3.1.1
• Fix class: content: A fix needs authored text.

Who it affects

• People who use a screen reader or a braille display, most of them blind.
• People with cognitive, learning or attention disabilities.

How to fix it

The value is a language name or a country code, such as english or jp

Use a BCP 47 tag, which starts with the language subtag: en for English, ja for Japanese, zh-Hant for Chinese in traditional script. Add a region only when it matters, such as en-GB.

<html lang="ja">
  <head>
    <title>料金プラン</title>
  </head>
  <body>
    <main>
      <h1>料金プラン</h1>
    </main>
  </body>
</html>

The value uses an underscore, such as en_US

Use a hyphen: en-US. Many locale settings use underscores, so convert the value where the template writes lang.

The value is left over from a template, such as undefined or an unfilled placeholder

Write the page’s language tag where the template renders lang, and make sure that value is always set.

Fixes that fail

Swapping in any valid tag, such as en, without checking the content’s language

axe checks only that the language subtag exists, so a wrong language passes. Screen readers then read the content with the wrong pronunciation.

More on the rule

axe-core’s documentation of the rule

CORA’s fix guidance adapts content from accessibility-agents, under the MIT License: see its notice.