Document Language: The One-Line Metric That Decides How a Screen Reader Pronounces Your Page

A screen reader opens your page and starts reading in French. Your page is in English. The reader is not broken and the page is not broken. The html element has no lang attribute, or it has the wrong one, and the screen reader is doing exactly what it was told. One attribute, set once, in the template, and 13.5 percent of the web forgets it.

The smallest failure in the Million data

The WebAIM Million 2026 report found missing document language on 13.5 percent of the top one million home pages. It is the least common of the six error types that account for 96 percent of all detected issues, and the easiest to fix. Low contrast text needs a design pass. Missing form labels need a markup pass across every form. Missing document language needs one attribute on one element in one template, and the error still shows up on more than one in eight home pages. That tells you something about how accessibility failures actually happen. They are not hard problems that resist fixing. They are one line fixes that nobody owns, in templates nobody re-reads after launch. The language attribute is set when the site is built and never checked again, and when a theme update or a migration drops it, nothing in the deploy pipeline notices.

WCAG 3.1.1, Language of Page, Level A, requires the default human language of each web page to be programmatically determinable. In practice that means lang equals en, or de, or fr, on the html element. It is a Level A criterion, the most basic level, and it exists because pronunciation is not a nicety. A screen reader loads a pronunciation engine per language, and the wrong engine turns ordinary English into something close to unintelligible. The user cannot fix it from their side. The page has to declare its language, or the reader guesses, and the guess is the reader default, which is usually right for that user but not guaranteed.

Wrong is worse than missing

A missing lang falls back to the screen reader default, which is usually the language the user reads in, so the damage is limited. A wrong lang actively misleads the reader: English text read with French pronunciation rules, or German text read as English. The wrong value usually arrives through a template copied from another site, a theme default that was never changed, or a migration that carried the old language code into a new market. The fix is the same one line, but the detection is different: a scanner that only checks for the presence of lang will pass a wrong value. Check the value against the actual content language, not just the presence of the attribute. A multilingual site needs this check per locale, because the template that serves en and de from the same codebase is the one most likely to hardcode one of them.

Mixed language content needs the second criterion. WCAG 3.1.2, Language of Parts, Level AA, requires the language of each passage to be programmatically determinable. A page in English with a French quote, a Spanish product name, or a German legal term needs a lang attribute on the element that holds the passage. The screen reader switches engines mid page, which is the correct behaviour, and the user hears the quote pronounced as French instead of as mangled English. Most sites never need this, because their content is one language. The sites that do need it are the ones that quote, cite, or sell across languages, and they are the ones least likely to have it.

The check that belongs in the deploy gate

Add two assertions to the template test: the html element carries a lang attribute, and its value matches the content language of the page. Run it per locale, not once globally, because a hardcoded lang equals en on a German page is a failure the global test will miss. Then check the pages that are generated rather than templated: error pages, PDF landing pages, and the checkout, which often ships from a different template than the marketing site and carries a different, older lang value or none at all. The whole check takes ten minutes and the fix takes one line. The reason it is still missing on 13.5 percent of home pages is not difficulty. It is that nobody put it in the gate.

Keep reading: Skip Link Coverage: The Metric Nobody Tracks Until the Complaint Arrives, Focus Not Obscured: Measuring 2.4.11 Instead of Guessing, Redundant Entry: The WCAG 2.2 Metric That Exposes Checkout Rework.

Frequently asked questions

What is the document language attribute?

It is the lang attribute on the html element, for example lang equals en for English. It tells browsers and assistive technology which language the page is written in, so a screen reader can load the right pronunciation rules. WCAG 3.1.1 Language of Page requires it at Level A.

How common is a missing document language?

The WebAIM Million 2026 report found missing document language on 13.5 percent of the top one million home pages. It is the least common of the six error types that account for 96 percent of all detected issues, but it is also the easiest to fix: one attribute, set once, in the template.

What happens when the lang attribute is wrong, not missing?

The screen reader pronounces the page in the wrong language. English text read with French pronunciation rules is close to unintelligible, and the user has no way to correct it. A wrong lang is worse than a missing one, because a missing lang falls back to the screen reader default, which is usually right for the user, while a wrong lang actively misleads it.

What about pages that mix languages?

WCAG 3.1.2 Language of Parts, Level AA, requires the language of each passage to be programmatically determinable. A page in English with a French quote, a Spanish product name, or a German legal term needs a lang attribute on that passage. Set the page language on the html element and the passage language on the element that holds the passage.