The valid-lang rule flags a lang attribute on an element inside the page – a quote, a language switcher link, a paragraph – whose value is not a valid language tag, such as fr_FR or french. Screen readers cannot switch to the right pronunciation for that passage. The fix is a well-formed tag: lang="fr".
What the rule means
WCAG 3.1.2 Language of Parts requires that software can determine the language of each passage or phrase that differs from the page language. In HTML you mark such a passage with lang on the element that wraps it.
valid-lang checks every element other than <html> that carries lang (or xml:lang). It takes the part before the first hyphen and compares it with axe-core's list of known language codes. It fails on:
- locale identifiers with an underscore:
fr_FR,de_DE; - language names instead of codes:
french,deutsch; - codes that do not exist, such as
dkfor Danish (correct:da).
It does not report:
- an empty
lang=""– that is allowed and means "language unknown"; - elements with no text of their own, such as an empty
<span lang="xx">; - a passage in another language with no
langat all. This is the most common failure of 3.1.2, and no automated rule can find it, because it needs someone to recognise the language.
WCAG 3.1.2 has exceptions: proper names, technical terms, words of indeterminate language, and words that have become part of the surrounding language, such as "kindergarten" in English, need no lang.
Who is affected
Mainly blind and partially sighted people using a screen reader. Screen readers such as NVDA, JAWS and VoiceOver can switch voice when the language changes – but only when the markup says so with a tag they can read. With an invalid tag, a French quote on an English page is read with English pronunciation and can become hard to understand. The same applies to translation tools and to people who use text-to-speech to support their reading.
Why the check fails
- Language switchers that print the CMS locale on each link:
lang="de_DE",lang="fr_FR". - Translation plugins that wrap translated snippets with their internal locale identifiers.
- Language names from an editor field, such as
lang="english", entered in a rich-text editor's "language" option. - Typos and country codes:
lang="jp"instead ofja,lang="dk"instead ofda. - Template placeholders that were never replaced, for example
lang="{{ item.locale }}".
How to fix it
- Find where the value comes from – usually the language switcher template or the plugin that marks up translations.
- Write BCP 47 tags: the language code, optionally a hyphen and a region (
fr,fr-CA). Replace underscores with hyphens. - While you are there, mark up passages in other languages that have no
langyet – the rule will never point you to them.
<!-- Before: locale identifiers on the language switcher -->
<nav class="lang-switch" aria-label="Language">
<a href="/de/" hreflang="de" lang="de_DE">Deutsch</a>
<a href="/fr/" hreflang="fr" lang="fr_FR">Français</a>
</nav><!-- After: valid language tags, so each name is read in its own language -->
<nav class="lang-switch" aria-label="Language">
<a href="/de/" hreflang="de" lang="de">Deutsch</a>
<a href="/fr/" hreflang="fr" lang="fr">Français</a>
</nav>A quote in another language is marked up the same way – on the element that contains exactly that passage:
<p>The motto of the house reads <q lang="fr">Liberté, égalité, fraternité</q>.</p>How to test it manually
- In the browser console, list all language changes:
document.querySelectorAll('[lang]'). Check each value against the IANA language subtag registry. - Read the page and look for words and passages in another language that have no
lang– quotes, product names that are full phrases, song or film titles, the names of other language versions in the switcher. - Listen with a screen reader (NVDA on Windows, VoiceOver on macOS) with automatic language switching turned on: does the voice change where the language changes?
- Remember the exceptions: proper names and established loan words need no markup.
Related WCAG criterion
3.1.2 Language of Parts, Level AA. Related: 3.1.1 Language of Page, which covers the page language on <html> and uses the same tag format.
How Reviseberg reports it
Reviseberg runs valid-lang on every crawled page at 1280px. Language switchers sit in the header, so an invalid tag there shows up as one element per language link on every page. The issue list shows the rule with its severity, WCAG criterion 3.1.2 and level, the number of elements and pages, and the points you get back by fixing it. The detail view shows the selector, the HTML snippet with the invalid value and every affected page. You can mark a finding as "ignore", "can't fix" or "false positive" with a reason; every decision is logged.
Because passages without any lang cannot be found automatically, a crawl with no findings does not make 3.1.2 a pass: the criterion shows as partly checked until a person records a manual result.
Related rules
- undefined – the same check for the page language on
<html>. - undefined – the page has no language at all.
- undefined – links, such as those in a language switcher, need a readable name.
Check the language markup across your whole site – get a free scan