AccessLint Rule: The lang attribute must have a valid value on all elements.

About this AccessLint rule

When a page contains text in a language different from the document's primary language, the lang attribute on the wrapping element tells assistive technologies which language rules to apply. If the value of that lang attribute is not a valid BCP 47 language tag, screen readers cannot switch to the correct pronunciation and inflection. The result is garbled or misleading speech output for users who rely on screen readers.

For example, a French quotation inside an English page should be wrapped in an element with lang="fr". If the attribute instead contains a typo like lang="fren" or an invented code like lang="xyz", the screen reader has no way to identify the language. It will either read the text with English pronunciation rules or fall back to unpredictable behavior depending on the assistive technology.

This rule applies to any HTML element inside <body> that has a non-empty lang attribute and contains human-language text. The primary language subtag in the value must be recognized — meaning it must be a valid subtag registered in the IANA Language Subtag Registry. Region subtags (like CH in fr-CH) and other subtags after the primary tag are not checked by this rule; only the primary language subtag matters.

Which users are affected

Screen reader users are the most directly affected. Screen readers like JAWS, NVDA, and VoiceOver use the lang attribute to load the correct text-to-speech voice and pronunciation dictionary. An invalid language tag prevents the correct voice from loading, so the text is read with the wrong pronunciation. This can make content unintelligible.

Users of braille displays are also affected, since the lang attribute determines which braille translation table is used.

Related WCAG success criteria

This rule maps to WCAG 2 Success Criterion 3.1.2: Language of Parts (Level AA). SC 3.1.2 requires that the human language of each passage or phrase in the content can be programmatically determined. A lang attribute with an invalid value fails to meet this requirement because assistive technologies cannot determine the language from it.

How to fix it

Identify every element that has a lang attribute.
Check that the value starts with a valid primary language subtag. Common valid subtags include en, es, fr, de, zh, ja, pt, ar, ru, ko, it, nl, hi, and sv.
Replace any invalid or misspelled subtag with the correct BCP 47 code. You can look up codes in the IANA Language Subtag Registry.
If the element does not actually contain text in a different human language (for example, a <code> element where lang was mistakenly used to indicate a programming language), remove the lang attribute entirely.

Region and script subtags after the primary subtag are optional. lang="fr" and lang="fr-CA" are both valid. The primary subtag is what matters for this rule.

Examples

Invalid language tag

The lang attribute has a value that is not a recognized language subtag:

<html lang="en">
  <body>
    <p lang="fren">
      Ils ont trouvé un étrange bar Tiki aux abords de la petite ville balnéaire.
    </p>
  </body>
</html>

fren is not a valid BCP 47 primary language subtag. A screen reader cannot determine the language and will likely read this French text using English pronunciation.

Valid language tag

Use the correct two-letter (or sometimes three-letter) subtag:

<html lang="en">
  <body>
    <p lang="fr">
      Ils ont trouvé un étrange bar Tiki aux abords de la petite ville balnéaire.
    </p>
  </body>
</html>

fr is a valid subtag for French. The screen reader can switch to a French voice for this paragraph.

Valid language tag with region subtag

Region subtags are allowed and do not cause failures:

<html lang="en">
  <body>
    <blockquote lang="fr-CH">
      Ils ont trouvé un étrange bar Tiki aux abords de la petite ville balnéaire.
    </blockquote>
  </body>
</html>

fr-CH identifies Swiss French. The primary subtag fr is valid, so this passes the rule. Even if the region subtag were syntactically unusual, the rule only checks the primary subtag.

Empty lang attribute (not flagged by this rule)

<html lang="en">
  <body>
    <span lang="">Bonjour</span>
  </body>
</html>

An empty lang attribute is outside the scope of this rule because the value is empty. However, an empty lang value has its own meaning in HTML (it indicates that the language is unknown) and may be flagged by other rules.