All rules

Sheath rule

a11y-html-lang

The <html> element must have a lang attribute for accessibility.
Package
Core
Category
Accessibility
Default severity
error by default
Auto-fix
Auto-fix available

(dangerous unless default is configured)

#Why

The lang attribute helps screen readers pronounce content correctly and assists translation tools. It's required by WCAG 2.2 Success Criterion 3.1.1 (Language of Page).

#Examples

#Bad

<!-- Missing lang attribute -->

<html>

    <head>...</head>

    <body>...</body>

</html>



<!-- DOCTYPE present but lang missing -->

<!DOCTYPE html>

<html>

    <head>...</head>

</html>

<!-- Empty lang is non-conforming: it declares the language unknown -->

<html lang="">

    <head>...</head>

</html>



<!-- Locale underscores are not BCP 47 separators -->

<html lang="en_US">

    <head>...</head>

</html>

#Good

<!-- English -->

<html lang="en">

    <head>...</head>

    <body>...</body>

</html>



<!-- French -->

<html lang="fr">

    <head>...</head>

</html>



<!-- With region code -->

<html lang="en-US">

    <head>...</head>

</html>



<!-- Portuguese (Brazil) -->

<html lang="pt-BR">

    <head>...</head>

</html>

#Options

Use this option to set the language inserted by auto-fix.

Option Type Default Description
default string 'en' Default language code for auto-fix 
<?php



'a11y-html-lang' => ['error', ['default' => 'en']],

#Auto-fix

The fixer adds lang="en" (or configured default) to the html element; an empty lang="" is rewritten to the default the same way:

<!-- Before -->

<html>



<!-- After -->

<html lang="en">

The built-in English default is an assumption, so that fix requires --dangerous. Once the project explicitly configures default, the chosen language is treated as project knowledge and a plain --fix may apply it.

#Notes

  • Static values must use a well-formed BCP 47 language tag. Malformed values such as en_US are reported; use en-US instead
  • lang="" is reported too: an empty tag is non-conforming and tells assistive technology nothing. A dynamic value (lang="{{ app()->getLocale() }}", :lang="$locale") is left alone
  • Common codes: en, es, fr, de, zh, ja, pt, ru
  • Include region for locale-specific content: en-US, en-GB, pt-BR
  • Opaque attribute spreads such as {{ $attributes }} make the final lang value unknowable and are not checked. The element is reported when any explicit Blade branch can omit lang

#References

#Related Rules