probeo

How to fix a page with no lang attribute, or an invalid one?

html-has-lang page

The issue

A page that doesn’t declare its language is read aloud in whatever language the screen reader assumes. An English page on a device set to French is spoken with French pronunciation rules, and words become hard or impossible to follow. Braille translation and browser features such as automatic hyphenation rely on the same declaration.

The cause is a missing, empty or unrecognized lang on the <html> element. Templates often omit it, or fill it with a placeholder or a misspelled code. WCAG 3.1.1 requires the default human language of each page to be identifiable by software.

Scope

Two rules check the <html> element:

  • html-has-lang reports it when neither lang nor xml:lang has a value.
  • html-lang-valid reports it when lang is present but its primary subtag, the part before the first hyphen or underscore, isn’t a recognized language code. en, en-US and pt_BR pass; english, xx and us don’t.

Language changes inside the page, on other elements, are checked separately by valid-lang.

How to check you have it

  • In probeo: the page reports html-has-lang, “<html> element must have a lang attribute”, or html-lang-valid, “<html> element must have a valid value for the lang attribute”. Both have serious impact and map to WCAG 3.1.1.
  • By hand: view the page source and read the opening <html> tag. It should carry lang with the page’s language code, such as lang="en".
  • With a tool: axe DevTools reports both rules by the same names, and Lighthouse’s accessibility audit checks the same thing.

The fix

Set lang on the <html> element to the code for the page’s main language.

Use a language code, optionally with a region: en, en-US, es, fr-CA. The value should be the language most of the page’s text is in, which on a translated site differs from page to page.

<html lang="en-US">

Set it in the template that renders <html>, so every page inherits it, and have each language version of a translated site set its own.

Done when: every page’s <html> element declares a valid language code for its content, and the check above comes back clean.

Do not

  • Do not write the language name instead of the code, as in lang="English".
  • Do not use a country code as a language code, as in lang="us" or lang="uk" for English.
  • Do not leave a site-wide lang="en" on pages translated into other languages.

FAQ

Is xml:lang enough?

It satisfies html-has-lang, which accepts either attribute. But html-lang-valid reads only lang, and HTML documents are expected to use lang. Set lang, and if you keep xml:lang as well, make it match.

Does the region part matter?

Not to these rules: only the primary subtag is checked, so en-US and en-GB both pass. The region can still matter to a screen reader choosing an accent or a spelling dictionary.

Is this the same as the SEO lang check?

It is the same attribute, checked for a different reason. The Technical SEO page on lang covers it from the search side.

Which product detects this

Probeo checks this on every page of your site as part of Site Clarity. This page explains one instance; the product tells you every page that has it.