Language Rule

The page language code must be valid html-lang-valid

A lang attribute only works if its value is a real language tag: a two or three letter code like en, cy or fr, optionally followed by a hyphen and a region, like en-GB. Anything else is ignored, which is the same as having no lang at all. The screen reader falls back to its default voice.

WCAG 2.2 A 3.1.1 Language of Page

Websight reports this as <html> element must have a valid value for the lang attribute

Who it affects

Someone using a screen reader set to Polish opens the museum's English page, which has lang="english". The value is ignored, so the Polish voice reads the English text and it is unintelligible.

Someone relying on automatic translation is offered a translation from the wrong language, or none.

The developer who copied lang="en_US" from a config file has no idea anything is wrong, because browsers do not warn.

Broken versus fixed

The broken markup is shown as code rather than rendered, because the effect is in how it is announced or handled, not how it looks.

Broken
<html lang="english">

Not a language tag. Screen readers ignore it and carry on in whatever voice they were already using, so English may be read with Polish or German pronunciation.

Fixed
<html lang="en">

en is the code for English. Add -GB for British English if you want a British voice and spelling.

Test it by hand in two minutes

  1. View the page source and read the lang value. It should be letters only, with a hyphen before any region: en, en-GB, cy, fr-CA.
  2. If you are not sure of the code, look the language up in the ISO 639-1 list; most common languages have a two-letter code.
  3. Check the separator. en-GB is right; en_GB is wrong.
  4. Run document.documentElement.lang in the console and compare it with the language you can see on the page.

The fix

Before
<html lang="english">
After
<html lang="en">

Language code first, then an optional region after a hyphen. Case does not matter, but the usual style is a lowercase language and an uppercase region.

Underscore from a programming locale

Before
<html lang="en_GB">
After
<html lang="en-GB">

Programming locales use underscores; HTML language tags use hyphens.

Country instead of language

Before
<html lang="gb">
After
<html lang="en-GB">

The first part is always the language, never the country. gb is not a language.

Common mistakes

  • lang="uk" to mean United Kingdom; it means Ukrainian.
  • lang="en-UK"; the region code for the United Kingdom is GB.
  • Full words such as lang="French" or lang="deutsch".
  • Leaving lang="" empty, which counts as missing.

WCAG criteria this rule maps to

axe-core tags this rule as WCAG 2.2 level A. It is one of the checks for:

The scanner checks that the value of lang on the html element is a well-formed language tag with a known primary language. It cannot tell whether the language matches the page text, and it does not strictly validate rare region or script subtags. Automated tools find only part of the accessibility problems on a page; a pass on this rule is not a pass on the criterion.

A The page must say what language it is in html-has-lang The lang attribute on the html element tells browsers and screen readers which language the page is written in. AA Language codes on page sections must be valid valid-lang When part of a page is in a different language from the rest, put a lang attribute on that element. A lang and xml:lang must name the same language html-xml-lang-mismatch Some pages, usually ones generated as XHTML or from older templates, carry both a lang attribute and an xml:lang attribute on the html element.

Scan your own page for this and 63 other checks

Open any page in Chrome, click Websight, and get a score out of 100 with every issue explained and a draft fix snippet per element.

Add Websight to Chrome

Free scans, no account, nothing leaves your computer. Automated tools find only part of the problems; the extension says so on every report.