NeovaAdvanced SEO Platform

<html> Element Must Have a Valid Value for the Lang Attribute

In Neova Runs from the crawl itself: nothing to set up.

Rule last reviewed October 17, 2026 · Guide updated July 7, 2026

The lang value must be a valid BCP 47 language tag, such as en, en-US or pt-BR (HTML standard, WCAG 3.1.1).

How Neova Finds It

Neova reads the HTML of every page it crawls and looks for this.

Why It Matters

Proper HTML structure helps crawlers parse and understand page content correctly.

The Ticket It Writes

HT-022 · <html> Element Must Have a Valid Value for the Lang Attribute

How to Check the Fix: 1. Run the check again in Neova
2. Spot-check sample URLs across affected templates
3. Record the re-check date and period label next to the baseline

Neova writes this ticket for every affected page group and sends it to Jira, Linear, Asana and the rest, after you approve it.

The Full Guide

What This Check Flags

This check fails when the <html> element has a lang attribute but its value is not a valid language tag — things like lang="english", lang="en-UK", or lang="us". The attribute is present, so it looks handled, but the value is garbage to a machine: screen readers cannot pick the right pronunciation engine, and browser translation and language detection get confused.

This is the trickier sibling of the missing-attribute problem. If the lang attribute is absent entirely, that is a different check — HTML Element Must Have a Lang Attribute. This one assumes you remembered the attribute but got the value wrong, which is arguably worse: a wrong value can actively mislead, where a missing one at least fails visibly.

A Real Failing Example, and the Fix

The values that fail are the ones that feel right to a human but do not follow the BCP 47 / ISO format machines expect:

<!-- All invalid -->
<html lang="english">      <!-- full name, not a code -->
<html lang="EN_US">        <!-- underscore; region uppercase but wrong sep -->
<html lang="en-UK">        <!-- "UK" is not the region code; it is GB -->
<html lang="us">           <!-- that's a country, not a language -->

The correct form is a two-letter ISO 639-1 language code, optionally followed by a hyphen and a two-letter ISO 3166-1 region code. Fix each of the above:

<html lang="en">           <!-- English -->
<html lang="en-US">        <!-- English, United States -->
<html lang="en-GB">        <!-- English, United Kingdom (GB, not UK) -->
<html lang="fr-FR">        <!-- French, France -->

Rules of thumb: use a hyphen, not an underscore; the language subtag is lowercase; the region subtag is uppercase; and the region is the ISO 3166 code, which is why the United Kingdom is GB even though the country's informal abbreviation is "UK."

Valid Codes vs. the Invalid Values That Mimic Them

This is where most failures come from — a plausible-looking value that is not actually a valid tag. Left column is what you meant; right column is the wrong version this check keeps catching:

Language / Locale Valid Value Common Invalid Value
English en english, eng, EN (case aside)
English (US) en-US en_US, en-us-1, us
English (UK) en-GB en-UK, en-uk
French fr french, fra, fr-FR-x
Spanish (Spain) es-ES es_ES, spanish, sp
Chinese (Simplified) zh-Hans chinese, zh-CN-simplified
Portuguese (Brazil) pt-BR pt_br, brazilian, br

Note zh-Hans: that middle part is a four-letter script subtag (ISO 15924), used when script matters more than region. It is valid — a reminder that "two-letter only" is the common case, not the whole rule.

How to Detect It

  1. Run an automated checker (axe, Lighthouse, WAVE). The rule "html element must have a valid lang attribute value" flags a present-but-malformed value distinctly from a missing one.
  2. View source and read the opening <html> tag. Eyeball the value for full words, underscores, or "UK" where "GB" belongs.
  3. Validate the tag against BCP 47 — the W3C internationalization language-tag checker confirms whether a value is well-formed and registered.
  4. Audit templated or CMS-generated pages, where a site setting like "English" may be written straight into lang instead of being mapped to en.
  5. Check per-page overrides. A multilingual site may set a valid site default but emit a bad value on translated templates.

How to Fix It

  1. Replace the value with a well-formed BCP 47 tag: lowercase ISO 639-1 language, optional uppercase ISO 3166-1 region, hyphen-separated.
  2. Swap full language names for codes (english → en) and underscores for hyphens (en_US → en-US).
  3. Correct region confusions — en-UK becomes en-GB; do not put a country name where a language belongs.
  4. Fix it at the source: if a CMS or theme setting generates the value, map the human-readable label to the correct code once, so every page inherits it.
  5. Re-run the validator to confirm the value is now recognized, and add a language subtag on any inline content that switches languages mid-page.

FAQ

How Is This Different From the "Must Have a Lang Attribute" Check?

That check fires when the attribute is missing; this one fires when it is present but invalid. Two distinct states: no attribute at all versus an attribute holding a value like english or en-UK that no parser recognizes. You can fail this one while technically "having" a lang attribute.

Why Is en-UK Wrong When Everyone Writes "UK"?

The region subtag uses ISO 3166-1 codes, and the code for the United Kingdom is GB, not UK. "UK" is a common informal abbreviation but is not the registered region code, so en-GB is the valid tag for British English.

Do I Need the Region Part at All?

No. A bare language code like en or fr is completely valid and often the right choice. Add a region subtag only when the locale genuinely matters — for pronunciation, spelling, or formatting differences between, say, en-US and en-GB.

Is Capitalization Enforced?

By convention the language subtag is lowercase and the region subtag is uppercase (en-US), and script subtags are title case (Hans). Tags are technically case-insensitive for matching, but following the convention avoids confusion and keeps validators and tooling happy.

Does an Invalid Lang Value Hurt SEO?

It is primarily an accessibility and localization issue — wrong pronunciation, broken browser translation. Google mostly infers page language from content rather than the lang attribute, but a correct value supports a clean multilingual setup. If you run multiple languages, pair it with proper hreflang implementation, and see the language attribute glossary entry for the fundamentals.

Written by Neova Labs · Back to the Check Library