SiteLint documentation and guidelines

Page must declare LANG attribute on the HTML element.

Description

A page read aloud in the wrong voice is confusing from the first word. Screen readers, braille displays, and translation tools choose pronunciation rules from the language declared on the html element; when that value is missing, empty, or malformed, assistive technology falls back to a default voice and mispronounces content. WCAG Success Criterion 3.1.1 makes this declaration a Level A requirement.

Valid values follow BCP 47, for example en, en-GB, or ru-Cyrl-BY. The audit reads the root element and reports a missing attribute, a blank value, an invalid tag, or a tag with more than three subtags, including underscore separators such as en_US. Setting the language correctly improves accessibility, helps browsers select fonts and hyphenation, and gives search engines a clearer signal about the primary language of the page.

Disabilities impacted

  • Visual: Screen reader and braille display users depend on the declared language to select pronunciation and contraction rules; a missing or wrong value produces garbled output.
  • Cognitive: Readers with dyslexia or language processing difficulties benefit from correct pronunciation and accurate translation, which reduce the effort needed to understand text.
  • Screen reader: Assistive technology switches voices and dictionaries based on the root language; an invalid tag forces a default voice and mispronounces words throughout the page.
  • Motor: Voice control and dictation users rely on language identification to load the right recognition grammar, improving command and text-entry accuracy.

Why it matters

Language metadata shapes whether people can consume content at all. Correct pronunciation and braille contraction rules – including region-specific vocabulary – lower cognitive load, improve comprehension for non-native readers, and make translated snippets more accurate in search results. That reliability also supports ADA and Section 508 obligations, reduces support complaints, and prevents the subtle exclusion that happens when an entire page sounds foreign to the technology meant to read it.

Coding problems and solutions

Common coding problems

  • Missing attribute: The html element has no lang attribute at all, so assistive technology must guess the language.
  • Empty value: Attributes such as lang="" or whitespace-only values are present but carry no usable information.
  • Incorrect separator: Values like en_US use an underscore instead of the required hyphen between subtags.
  • Non-tag value: Words such as English or foobar are written instead of a real language code.
  • Too many subtags: Tags such as zh-Hant-TW-x-private contain four subtags and exceed the three-part limit applied by this audit.
  • Wrong element: The language is placed on body or a wrapper div while the root html element is left undeclared.

How to fix it

Declare the language on the root element

Add a lang attribute directly to html, using the language of the majority of the page content.

Correct example
<!DOCTYPE html>
<html lang="en">
<head>
  <title>Sample page</title>
</head>
<body>
  <p>Content in English.</p>
</body>
</html>
Incorrect example
<!DOCTYPE html>
<html>
<head>
  <title>Sample page</title>
</head>
<body>
  <p>Content in English.</p>
</body>
</html>

Use valid BCP 47 syntax

Separate subtags with hyphens and use registered codes; grandfathered tags such as i-default are also accepted.

Correct example
<html lang="en-GB">
  <body>
    <p>Content in British English.</p>
  </body>
</html>
Incorrect example
<html lang="en_GB">
  <body>
    <p>Content in British English.</p>
  </body>
</html>

Keep the tag within three subtags

Prefer a concise language, script, and region combination; extension subtags push the value past the limit enforced by this check.

Correct example
<html lang="fr-FR">
  <body>
    <p>Contenu en français</p>
  </body>
</html>
Incorrect example
<html lang="fr-FR-x-private">
  <body>
    <p>Contenu en français</p>
  </body>
</html>

Mark passages in other languages

Keep the root language accurate and add lang on individual elements when a section switches language.

Correct example
<html lang="en">
  <body>
    <p>Default English content.</p>
    <p lang="fr">Bonjour, comment allez-vous ?</p>
  </body>
</html>
Incorrect example
<html lang="en">
  <body>
    <p>Default English content.</p>
    <p>Bonjour, comment allez-vous ?</p>
  </body>
</html>

Keep the language in sync in client-side apps

When routes change the displayed language, update document.documentElement.lang rather than a nested element.

Correct example
const setDocumentLanguage = (languageTag) => {
  document.documentElement.lang = languageTag;
};

const renderRoute = (route) => {
  setDocumentLanguage(route.languageTag);
  render(route.component);
};
Incorrect example
const setDocumentLanguage = (languageTag) => {
  document.body.setAttribute('lang', languageTag);
};

Known Limitations

  • Root element only: The audit inspects the document root exclusively; it does not validate lang attributes placed on nested elements or inline passages.
  • SPA route changes: Single-page apps that swap content without updating the root attribute after the initial scan are not rechecked by this rule.
  • Iframes and shadow DOM: Embedded documents and shadow trees have separate roots and fall outside the scanned element.
  • Tag validation approximation: Validity relies on Intl.getCanonicalLocales plus custom rules, so extension-heavy tags with four or more subtags are reported even when BCP 47 permits them.
  • Grandfathered exceptions: A fixed allowlist of grandfathered tags is accepted; uncommon legacy tags missing from that list may be flagged as invalid.
  • Content mismatch: The check confirms the attribute exists and is well formed but cannot tell whether the declared language matches the text actually rendered on the page.

Resources

Rule

  • Audit: accessibility
  • Standard: WCAG
  • Level: A
  • Success Criteria: 3.1.1
  • Rule ID: html-lang-attr