probeo

How to correctly add a lang attribute to the <html> element?

html-lang-missing page

The issue

A page without a lang attribute can be read aloud in the wrong language. Screen readers pick their pronunciation rules from it, so an English page announced with French rules is close to unintelligible. Browsers also use it to decide whether to offer translation, and how to hyphenate and spell-check.

The cause is a missing lang on the <html> element. It is also a WCAG 2.1 failure, under 3.1.1 Language of Page. Google says it determines a page’s language from its visible content, not from lang, so the cost falls mostly on visitors, not rankings.

Scope

Each page declares its own language on its <html> element. On a multilingual site, the template has to set the value per page rather than hard-code one.

How to check you have it

  • In probeo: the page reports Missing <html lang="..."> attribute. Probeo accepts lang or xml:lang.
  • By hand: view the page source and read the opening <html> tag. In the browser console, document.documentElement.lang returns the value, or an empty string.
  • With a tool: WAVE and other accessibility checkers report a missing document language.

The fix

Add a lang attribute to the <html> element with the code for the page’s main language, such as lang="en" or lang="en-US".

Use a BCP 47 tag: a language code, optionally followed by a region. The convention is lowercase language and uppercase region, as in fr-CA. Set it from the page’s own language, so translated pages each declare theirs.

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

Do not

  • Do not omit lang from the <html> element.
  • Do not use a code that isn’t a valid language tag.
  • Do not declare a language other than the one the content is in.
  • Do not rely on a Content-Language header in place of the attribute.

FAQ

Should region codes be included for all languages?

Only where the region changes the content, such as en-US and en-GB for different spelling. Plain en is right when the page serves every English reader.

What language code should mixed-language pages use?

The page’s main language on <html>, and a lang attribute on each element in another language. An English page quoting French uses lang="en" on <html> and lang="fr" on the quotation.

How does the lang attribute interact with the Content-Language HTTP header?

For a screen reader or a browser, the lang attribute is the declaration of the content’s language. The Content-Language header describes the intended audience of the response, and isn’t a substitute. Google says it ignores code-level language information such as lang when deciding a page’s language, so set lang for visitors and use hreflang for search engines.

Should translated page versions use different lang attributes?

Yes. Each version declares its own language. Connect the versions with hreflang links, which is what search engines use to show the right version to the right audience.

What prevents lang attributes from becoming incorrect when content changes?

Nothing automatic. A template that hard-codes lang="en" keeps declaring English on pages translated later. Set the value from the page’s language field, not the template.

Can multiple lang values be specified for multilingual content?

Not on <html>, which takes one value. Mark the other languages on the elements that contain them.

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.