Skip to main content
Understandable WCAG 3.1.1

3.1.1 Language of Page

The default human language of each web page can be programmatically determined.

Level A Serious WCAG 2.0 (new) WCAG 2.1 WCAG 2.2
html-has-lang html-lang-valid html-xml-lang-mismatch

What this rule means

WCAG 3.1.1 requires that each web page identifies its primary language using the lang attribute on the <html> element. This allows assistive technologies, browsers, and search engines to process the content correctly — including selecting the right pronunciation rules for screen readers and the correct fonts and text direction for rendering.

The lang attribute must use a valid BCP 47 language tag (e.g., "en", "fr", "tr", "zh-Hans"). An invalid or missing language declaration means assistive technology must guess, often resulting in garbled pronunciation for screen reader users.

Why it matters

Screen readers use the page language to load the correct pronunciation engine. When a Turkish page lacks lang="tr", a screen reader may attempt to read Turkish words with English pronunciation rules, rendering the content unintelligible. This affects millions of screen reader users worldwide.

Beyond accessibility, the lang attribute helps browsers offer translation, aids search engines in serving the right language version, and enables CSS features like :lang() selectors and language-specific hyphenation. It is one of the simplest and most impactful HTML attributes you can set.

Related axe-core rules

  • html-has-lang — Ensures the <html> element has a lang attribute.
  • html-lang-valid — Ensures the lang attribute value is a valid BCP 47 language tag.
  • html-xml-lang-mismatch — Ensures xml:lang and lang attributes match on the <html> element.

How to test

Automated tools reliably catch missing or invalid lang attributes. Manual verification is needed to confirm the language tag matches the actual page content.

  • Run axe DevTools or Lighthouse — check for html-has-lang and html-lang-valid violations.
  • Inspect the <html> element in DevTools and verify the lang attribute is present and correct.
  • For XHTML pages, check that xml:lang matches the lang attribute.
  • Verify the language tag matches the primary language of the page content, not just the interface.

How to fix

Add a valid lang attribute to the <html> element:

Bad practice

<!-- Missing lang attribute -->
<html>
  <head><title>My Page</title></head>
  <body>...</body>
</html>

<!-- Invalid lang value -->
<html lang="english">
  <head><title>My Page</title></head>
  <body>...</body>
</html>

Good practice

<!-- English page -->
<html lang="en">
  <head><title>My Page</title></head>
  <body>...</body>
</html>

<!-- Turkish page -->
<html lang="tr">
  <head><title>Sayfam</title></head>
  <body>...</body>
</html>

<!-- XHTML with matching attributes -->
<html lang="en" xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">
  <head><title>My Page</title></head>
  <body>...</body>
</html>

Common mistakes

  • Omitting the lang attribute entirely — the most common issue, especially in boilerplate templates.
  • Using an invalid language subtag like "english" or "turkish" instead of "en" or "tr".
  • Setting the wrong language — for example, lang="en" on a page whose content is primarily in Turkish.
  • Mismatch between lang and xml:lang on XHTML documents.
  • Using a region subtag without the base language (e.g., lang="US" instead of lang="en-US").

Resources