Missing language declaration

document/lang-missing

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-missing

Why we flag this

Screen readers read aloud with incorrect pronunciation.

Missing lang attribute.

What the rule checks

Scope. The root html element of the top-level document; every HTML page.

Expectation. Fails when the root html element has no lang attribute, or one whose value is empty or only whitespace: ACT b5c3f8 requires a lang attribute with a non-empty value, and lang="" explicitly declares the language unknown (HTML §3.2.6.2), so the page language is not programmatically determinable. xml:lang alone has no effect in text/html. A non-empty value, valid or not, passes this id; its validity is document/lang-invalid. A lang set by script before the audit reads the DOM counts like markup. Embedded documents are html-has-lang. One finding at the html element.

Source. WCAG 2.2 SC 3.1.1 Language of Page; ACT b5c3f8 (HTML page has lang attribute); H57; HTML §3.2.6.2 the lang attribute

Detection: shared; needs dom.

Failing example

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

missing_lang.htmlHTML

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>Missing lang corpus case</title>
</head>
<body>
    <main>
        <h1>Page without a lang attribute</h1>
        <p>The html element above has no lang attribute.</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.