probeo

How to fix an invalid lang attribute inside the page?

valid-lang page

The issue

A quotation, a product name or a section in another language is read with the page’s pronunciation unless it is marked. When it is marked with a code the screen reader doesn’t recognize, the switch fails and the passage is read as if it were in the page’s main language. A Spanish testimonial on an English page comes out garbled.

The cause is an invalid value in a lang attribute on an element inside the page, often a language name, a typo or a country code. WCAG 3.1.1 covers the page’s default language; marking changes of language within it is how the rest of the text stays readable.

Scope

Every visible element other than <html> that has a non-empty lang attribute is checked. Its primary subtag, the part before the first hyphen or underscore, must be a recognized language code. Elements hidden with hidden, aria-hidden="true", or an inline display: none or visibility: hidden, on the element or an ancestor, are skipped. The <html> element itself is checked by html-lang-valid.

How to check you have it

  • In probeo: the page reports valid-lang, “lang attribute must have a valid value”, with serious impact, on each element with an unrecognized code.
  • By hand: search the page source for lang= and read each value. Each should be a language code such as es, de or zh-Hant.
  • With a tool: axe DevTools reports the same rule by the same name.

The fix

Correct each lang value to the code for the language of that passage.

Use the language code, with a region or script only if it matters: es, fr-CA, zh-Hans. Put the attribute on the smallest element that holds the passage, so the switch begins and ends where the language does.

<blockquote lang="es">
  <p>El servicio fue rápido y claro.</p>
</blockquote>

Done when: every lang inside the page holds a valid code for its passage, and the check above comes back clean.

Do not

  • Do not write language names, as in lang="spanish".
  • Do not use country codes as language codes, as in lang="mx".
  • Do not mark a whole section as another language when only a phrase in it is.

FAQ

Do I need to mark every foreign word?

No. Words absorbed into the page’s language, such as “café” or “résumé” in English, are read correctly as they are. Mark passages and names a reader of the page’s language would mispronounce.

What about an empty lang attribute?

lang="" is skipped by this rule. In HTML it means the language is unknown, which is a legitimate value for text of no particular language.

Does this affect search engines?

This rule is about screen readers and other assistive technology. Search engines work out a page’s languages mostly from its visible text.

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.