Documentation/<html> needs lang

<html> needs lang

ZMD013

ZemDomu reports an HTML document whose root <html> element has a missing, empty, or invalid static lang value. Use the BCP 47 language tag that identifies the page's primary human language.

What this rule catches

  • Supported HTML documents whose root element has no lang attribute or an empty lang value.
  • Static lang values that do not match the rule's supported BCP 47 validation.

What static analysis cannot prove

  • Static analysis cannot prove that the declared language matches the page's actual content or pronunciation needs.
  • Language changes within the page and values selected only at runtime require additional review.

Standards classification and detection confidence

Classification
normative — The rule checks the document-language mechanism required for the page's default human language.
Detection confidence
high — Missing, empty, and unsupported static language tags are deterministic. The rule cannot verify that a syntactically valid tag matches the actual prose.

Applicable WCAG 2.2 criteria

Criterion 3.1.1 requires the default human language of each page to be programmatically determined.

Normative means the rule checks a machine-testable part of a cited standards requirement. Advisory means it enforces a documented authoring convention or supporting technique. Neither classification makes a ZemDomu result proof of WCAG conformance.

Examples

✅ Good

<!DOCTYPE html>
<html lang="en">
  <head>…</head>
  <body>…</body>
</html>

❌ Bad

<!DOCTYPE html>
<html>
  <head>…</head>
  <body>…</body>
</html>

Quick summary

When: The <html> element has no lang attribute, it is empty, or it is not a valid BCP 47 tag

Warning: <html> element missing or invalid lang attribute

Solution: Specify a valid language tag in the lang attribute (e.g., lang="en", lang="en-US", lang="sv-SE").

Why it matters

Accessibility: Without lang, screen readers may mispronounce content or apply incorrect reading rules.

SEO: Search engines lack language metadata, potentially lowering international indexing quality.

Rule details

In brief

  • Goal: Programmatically define the page’s language for assistive technologies.
  • What to do: Add a lang attribute (e.g., lang="en") to the <html> tag.
  • Why: Screen readers use this to select pronunciation and reading rules.

Intent

Prevent ambiguity in text-to-speech rendering by explicitly declaring page language.

Benefits

  • Improved screen-reader pronunciation and intonation.
  • Better SEO: search engines index content with correct language metadata.
  • Enhanced compliance: meets WCAG 3.1.1 and internationalization best practices.

Techniques

  • H57: Using the lang attribute on the HTML element (Sufficient technique for SC 3.1.1).

HTML Semantics

The lang attribute on <html> defines the document’s default human language per the HTML spec.

References

Tips & edge cases

  • Use BCP 47 language tags (e.g., en, en-US, fr-CA) for accuracy.
  • When serving XHTML as text/html, include both lang and xml:lang for compatibility.
  • For pages in multiple languages, wrap sections in <span lang="…"> or <p lang="…"> as needed.

See also

Related guides

Last verified: