ADA Compliance Professionals

    Lang attribute must have a valid value

    Last updated:

    Who it helps:
    Blind
    Standard:
    WCAG 2.2 Level A

    Related Guides

    The html lang attribute must have a valid language value

    The html element must declare a valid primary language using a correct language code.

    This applies to every HTML document and any parts of a page that switch languages.

    It supports screen reader users and others who rely on correct pronunciation, braille tables, and text processing.

    Why It Matters

    Assistive technologies use the page language to choose the right voice, pronunciation rules, and braille tables. Without it, names, dates, and loanwords can be read incorrectly.

    Language metadata also affects spell checking, hyphenation, search indexing, and voice input. Users with low vision or dyslexia benefit from consistent speech output.

    For multilingual pages, marking language changes prevents jarring reading as the tool can switch voices and rules only where needed.

    Common Causes

    • Missing lang attribute on the html element.
    • Using an invalid code (e.g., english, en_US, or typos) instead of a valid BCP 47 tag.
    • Setting lang on body but not on html.
    • Forgetting to mark inline language changes (quotes, product names, code-switching).
    • Frameworks rendering pages without transferring lang from server to client.
    • Confusing text direction (dir) with language or omitting dir for right‑to‑left scripts.

    How to Fix

    • Set the page language on the root element:
    • Use a valid BCP 47 tag (e.g., en, en-US, fr-CA, es-419). Language in lowercase, region in uppercase.
    • In HTML documents, use lang. Use xml:lang only for XML/XHTML served as application/xhtml+xml.
    • Ensure only one primary language on the html element. Choose the language that best represents the majority of the content.
    • Mark language changes for phrases or sections with a lang attribute on the nearest element that wraps the change.
    • For right-to-left scripts (Arabic, Hebrew, Persian), add dir="rtl" on the element that contains that text. Do not use dir to set language.
    • Avoid deprecated or incorrect tags (e.g., iw for Hebrew; use he). Check the IANA subtag registry for validity if unsure.
    • In SPAs/MPAs, set lang on the initial HTML and update it when routing to pages with different primary languages.
    • Validate with an HTML validator and an accessibility checker to catch empty or invalid lang values.

    How to Test

    • Visual/Code check:
    • Inspect the html element and confirm lang is present and non-empty.
    • Verify the value is a valid BCP 47 tag (e.g., en, en-GB, pt-BR).
    • Scan the page for foreign words/phrases; ensure they are wrapped in elements with the correct lang.
    • For RTL content blocks, verify dir="rtl" is applied appropriately.
    • Screen reader check:
    • With NVDA or JAWS on Windows: open the page, confirm the announced language matches your expectation.
    • Read a section that changes language; confirm the voice or pronunciation switches only for that segment.
    • With VoiceOver on macOS or iOS and TalkBack on Android, repeat the checks on mobile.
    • Keyboard check (where applicable):
    • Tab through content containing language switches; ensure focus indicators and reading order remain correct while SR announces languages accurately.
    • Automated check:
    • Run an HTML validator and an a11y ruleset (e.g., axe, WAVE) to flag missing/invalid lang and unmarked language changes.

    Good Example

    HTML
    !doctype html>
<html lang="en-US">
<head>
  <meta charset="utf-8">
  <title>International Shipping Policies</title>
</head>
<body>
  <h1>Shipping</h1>
  <p>We offer global delivery. <span lang="es-ES">Gastos de envío</span> vary by region.</p>
  <p><span lang="ar" dir="rtl">سياسة الشحن</span> applies to Middle East orders.</p>
</body>
</html>

    Bad Example

    HTML
    !doctype html>
<html>
<head>
  <meta charset="utf-8">
  <title>Global Policies</title>
</head>
<body>
  <h1>Policies</h1>
  <p>We ship worldwide. Gastos de envío are listed below.</p>
  <p><span dir="rtl">سياسة الشحن</span> details follow.</p>
</body>
</html>

    Quick Checklist

    • html element includes a valid BCP 47 language tag in lang.
    • The lang value matches the main language of the page.
    • All foreign words/sections are wrapped with the correct lang.
    • Use dir="rtl" for Arabic/Hebrew/Persian text where needed; do not use dir to set language.
    • Avoid invalid codes (no underscores, no plain words like "english").
    • Keep language codes consistent across server and client routing.
    • Validate with HTML/a11y tools and verify with at least one screen reader.
    • Update documentation so teams know how to set lang for new pages.