HTML Element Must Have Valid Lang Attribute Value: How to Fix It
- August 25, 2024
- HTML Structure, Language
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
- 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.
- View source and read the opening
<html>tag. Eyeball the value for full words, underscores, or "UK" where "GB" belongs. - Validate the tag against BCP 47 — the W3C internationalization language-tag checker confirms whether a value is well-formed and registered.
- Audit templated or CMS-generated pages, where a site setting like "English" may be written straight into
langinstead of being mapped toen. - 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
- Replace the value with a well-formed BCP 47 tag: lowercase ISO 639-1 language, optional uppercase ISO 3166-1 region, hyphen-separated.
- Swap full language names for codes (
english→en) and underscores for hyphens (en_US→en-US). - Correct region confusions —
en-UKbecomesen-GB; do not put a country name where a language belongs. - 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.
- 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.
Claude Vincent is a technical SEO consultant focused on crawlability, rendering, and AI-search visibility. He writes the field guides and case studies at SEO ProCheck, with a bias toward the durable, unglamorous work that decides whether search engines and AI answer engines can actually read and cite a site.
About SEO ProCheck
Technical SEO consulting and GEO strategy with 20 years of enterprise experience. Case studies, resources, and tools for search and AI visibility.
Work With Me
Technical SEO audits, GEO strategy, site migrations, and international SEO. Hourly consulting for teams who need hands-on support, not just reports.
Subscribe to our newsletter!
