Invalid page language

document/lang-invalid

WCAG success criterion: 3.1.1 (level A)
Outcome class: Automatic. An automated check that can report a confirmed violation.
Area: Accessibility, Language & Clarity
Default severity: high
axe-core rule: document/lang-invalid

Why we flag this

Screen readers choose a wrong or the default pronunciation.

Invalid value in the html element's lang attribute.

What the rule checks

Scope. The root html element of the top-level document when its lang attribute has a non-empty value.

Expectation. Fails when the primary language subtag of the root's lang value is not a valid BCP 47 language subtag: "english" (not a registered subtag), "en_US" (the underscore is no subtag separator, so the whole value is the primary subtag). Region and script subtags ("en-GB", "de-AT") are valid. An absent or empty lang is not applicable here (ACT bf051a applies to non-empty values only); that case is document/lang-missing. One finding at the html element.

Source. WCAG 2.2 SC 3.1.1 Language of Page; ACT bf051a (HTML page lang attribute has valid language tag); BCP 47 (RFC 5646) §2.1

Detection: shared; needs dom.

Failing example

The check reports a violation here. Corpus case invalid_lang_code. The page may contain further findings for other rules.

invalid_lang_code.htmlHTML

<!DOCTYPE html>
<html lang="english">
<head>
    <meta charset="utf-8">
    <title>Invalid lang code corpus case</title>
</head>
<body>
    <main>
        <h1>Page with an invalid lang attribute</h1>
        <p>The html lang attribute above ("english") is not a 2-3 letter BCP 47 subtag.</p>
    </main>
</body>
</html>

Passing example

The check passes here and reports nothing. Corpus case structure_modal_dynamic. The page may contain further findings for other rules.

structure_modal_dynamic.htmlHTML

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title></title>
    <style>
        body { font: 16px/1.5 sans-serif; margin: 0 16px; }
        button { min-width: 44px; min-height: 44px; }
    </style>
</head>
<body>
    <!-- A consent wall (#783): the application has not rendered yet, and a
         script sets the page language and the document title and opens a modal
         dialog after load.
         While the dialog is open, the page's headings and main landmark are
         missing for the moment of measurement, not necessarily for the page. -->
    <div id="app"></div>
    <dialog id="consent" aria-label="Cookie settings">
        <p>We use cookies to remember your shopping basket.</p>
        <form method="dialog">
            <button value="accept">Accept</button>
            <button value="reject">Reject</button>
        </form>
    </dialog>
    <script>
        document.documentElement.lang = 'en';
        document.title = 'Cookie settings – Acme Hardware';
        document.getElementById('consent').showModal();
    </script>
</body>
</html>

This page is generated from the rule catalogue and the rule contracts; see therule overview for how the outcome classes are derived.