HTML lang Attribute: Fixing a Missing or Wrong Value

What the lang attribute actually does

The attribute sits on the root element of the document and applies to everything inside it unless a child element sets its own value:

<!DOCTYPE html>
<html lang="en-GB">
<head>
  <meta charset="utf-8">
  <title>Boiler servicing in Chesterfield | Northgate Heating</title>
</head>

That one value is read by several different pieces of software, and each does something different with it:

WCAG 2.2 has a second, related criterion: 3.1.2 Language of Parts, at Level AA. It asks that a passage in a different language from the rest of the page is marked with its own lang, so assistive technology can switch voice for that passage and switch back afterwards.

What lang does and does not do for search

This is where most confusion comes from, so it is worth being precise. Google's documentation on multilingual sites says it works out the language of a page mainly from the visible content, and that it does not rely on code-level signals such as the lang attribute. A page with lang="en" written entirely in Spanish will be treated as a Spanish page. A missing lang will not, on its own, stop an English page ranking for English searches.

That does not make the attribute pointless. It is an accessibility requirement, it affects how browsers treat the page, and other search engines and tools may use it as one signal among several. It also tends to be a symptom: a site with no lang, or with en-US on a British business, often has other untouched template defaults in the head.

Three neighbouring signals are often mixed up with lang. They do different jobs:

• lang on the html element describes the language of this document, for software that processes it.
• hreflang annotations tell search engines which other addresses hold the same content in another language or for another region. They matter only when you have more than one version. The hreflang language codes guide covers that syntax.
• og:locale tells social platforms the locale of the shared card, written with an underscore, such as en_GB. The og:locale guide covers it.

Choosing a valid value

The value is a language tag in the format defined by BCP 47, the internet standard for language identifiers. For almost every site it is either a two-letter language code on its own, or a language code followed by a hyphen and a two-letter region code.

Tags are case-insensitive, but the usual convention is a lower-case language and an upper-case region: en-GB. Do not add a region you do not mean. If a page is written for English speakers anywhere, plain en is more honest than picking a country.

Sites that serve more than one language

Each language version needs its own value on its own pages. The French pages of a bilingual site should say lang="fr" (or fr-FR, fr-BE and so on), not inherit the English value from a shared layout. The most common fault on multilingual sites is a single hard-coded value in the master template, which makes every translation claim to be English.

Finding the problem

Start with the raw HTML the server sends, because a script can change the attribute after the page loads and browser tools show only the final state.

curl -s https://example.co.uk/ | grep -io "<html[^>]*>"

Then compare it with what the browser ends up with. In the developer tools console, type:

document.documentElement.lang

If the first shows nothing and the second shows a value, a script is setting it. That is better than nothing for screen reader users, but anything that reads the HTML without running scripts, including many validators, sees no language. Move the value into the server-rendered markup.

What checkers report

• Lighthouse has two related audits in its accessibility category: one fails when the html element has no lang attribute, the other when the value is not a valid language tag.
• axe reports a missing value, an invalid value, and a mismatch between lang and xml:lang when both are present.
• The Meta Tag Analyzer reads the head of the page with the other tags, which makes it easy to see a lang of en-US next to an og:locale of en_GB and fix both together.

Test more than the home page. Blog posts, product pages, landing pages built in a page builder and checkout pages are often served by different templates, and each can have its own html tag.

The fix, step by step

Where to set it on common platforms

WordPress

Well-built themes print the attribute through the language_attributes() function in header.php, which reads the Site Language chosen under Settings, General. Choosing English (UK) there produces lang="en-GB".

<html <?php language_attributes(); ?>>

If changing the Site Language makes no difference, the theme has hard-coded the value. Edit it in a child theme rather than the parent, so a theme update does not undo the change. Multilingual plugins such as WPML and Polylang switch the value for each language through the same function, which is another reason not to hard-code it.

Shopify

Current Shopify themes set the value from the storefront's active language in layout/theme.liquid:

<html class="no-js" lang="{{ request.locale.iso_code }}">

If yours shows a fixed value, replace it with the Liquid variable, and check any alternative layout files such as a separate checkout or password layout. The published default language is set under Settings, Languages.

Next.js and other JavaScript frameworks

In the App Router the html element is written in the root app/layout.tsx, so the attribute goes there directly. Sites with several languages usually put the locale in a route segment and read it in that layout. In the Pages Router it belongs in pages/_document on the <Html> component, or is set for you by the built-in i18n routing. Avoid setting it with client-side code, because the first HTML the server sends will then have none.

export default function RootLayout({ children }) {
  return (
    <html lang="en-GB">
      <body>{children}</body>
    </html>
  );
}

Static sites and hand-built pages

Every file has its own html tag, so a search across the project is the quickest check. Most static site generators, such as Hugo, Eleventy and Jekyll, keep it in one base layout and read a language value from the site configuration.

Edge cases and things that trip people up

• xml:lang. Only needed for XHTML served as XML. On ordinary HTML pages it does nothing, and if it is present with a different value from lang, checkers flag the mismatch. Remove it, or make it match.
• The content-language meta tag. <meta http-equiv="content-language"> is not valid in current HTML and is not a substitute. The lang attribute takes precedence where both exist.
• Embedded content. An iframe carries its own document with its own html element. A widget in the wrong language needs fixing at its source, or a lang on the iframe's own page.
• Language switchers. Each option in a menu that lists languages by their own names, such as Cymraeg or Français, should carry that language's lang so it is pronounced correctly.
• Machine translation in the browser. When a visitor uses the browser's translate feature, the browser may update the attribute itself. That is not something to fix.
• SVG and MathML. Inline SVG inherits the page language; text inside it in another language can take its own lang in the same way.

Keeping it right

• One source of truth. Take the value from the CMS or site configuration in one layout, never typed into several templates.
• A check in your build or monitoring. Automated accessibility tests such as axe in a continuous integration pipeline catch a missing or invalid value before release.
• A note for editors. Tell content authors how to mark a foreign-language quotation in the editor. Many editors, including the WordPress block editor, let you add an attribute through the HTML view or a custom class.
• Review after theme changes. A new theme, page builder or checkout template is the most common way an old en-US creeps back.

For the rest of the head, the Meta Analyzer Guide explains each check the analyzer runs, and the Accessibility Guide covers the wider WCAG picture that lang is one small part of.