ADA Compliance Professionals

    HTML lang and xml:lang must match

    Last updated:

    Who it helps:
    Blind
    Standard:
    WCAG 2.2 Level A

    Related Guides

    HTML pages require a valid lang, and lang and xml:lang must match when both are present

    Intro:

    Set a valid primary language on the html element, and if xml:lang is present, its value must be identical to lang. This appears on the root html element and any inline language changes. Screen reader users, especially multilingual readers, rely on this to get correct pronunciation and voice selection.

    Why It Matters

    Screen readers choose pronunciation, braille tables, and voices based on the declared language. Missing or incorrect language tags cause mispronounced words, wrong inflection, and confusion.

    If a page mixes languages, marking the parts prevents abrupt, incorrect speech. Direction settings ensure right‑to‑left scripts display and read in the proper order. This benefits users with visual, cognitive, and language processing differences.

    Common Causes

    • No lang attribute on the html element.
    • Invalid or non‑standard codes (e.g., using underscores: en_US instead of en-US).
    • lang and xml:lang differ on XHTML pages.
    • Only setting a meta Content-Language tag and assuming it’s enough.
    • Not marking inline phrases in another language.
    • Omitting dir="rtl" for right‑to‑left languages.

    How to Fix

    1. Identify the page’s primary language.
    2. Set html lang to a valid BCP 47 tag (examples: en, en-US, es-419, zh-Hans, ar).
    3. If your document also uses xml:lang (common with XHTML), make the values identical to lang. Prefer lang in HTML5; include xml:lang only when needed by your format.
    4. Mark language changes inline on the smallest element that contains the different language content.
    5. For right‑to‑left languages, set dir="rtl" on the element that starts the RTL content. Use dir="ltr" if you need to force left‑to‑right.
    6. Do not rely on meta http-equiv="Content-Language" for assistive technology; it does not set the language for screen readers.
    7. Validate your tags and codes. Use standard BCP 47 tags with hyphens, correct casing, and no underscores.

    How to Test

    • Code inspection:
    • Confirm html has a lang attribute with a valid BCP 47 tag.
    • If xml:lang is present on html, verify it matches lang exactly.
    • Spot-check inline elements for correct lang where phrases switch languages.
    • Check dir on RTL content.
    • Keyboard check:
    • Navigate headings and links; ensure nothing breaks visually when focus moves through RTL areas.
    • Screen reader check:
    • With NVDA/JAWS/VoiceOver, read the page start. Confirm the expected voice and pronunciation.
    • Move through inline foreign phrases. Verify the voice switches appropriately.
    • Mobile/touch check:
    • With TalkBack or VoiceOver on mobile, read the page and inline phrases. Ensure correct language and reading order, especially for RTL content.
    • Automated checks:
    • Run an HTML validator and a language-tag validator to flag invalid codes or missing attributes.

    Good Example

    HTML
    !doctype html>
<html lang="en-GB" xml:lang="en-GB">
<head>
  <meta charset="utf-8">
  <title>Sample</title>
</head>
<body>
  <h1>Welcome</h1>
  <p>Our motto: <span lang="fr">Liberté, égalité, fraternité</span>.</p>
  <p><span lang="ar" dir="rtl">مرحبًا بكم</span> — Arabic greeting.</p>
</body>
</html>

    Bad Example

    HTML
    !doctype html>
<html lang="en_US" xml:lang="en"> <!-- invalid tag and mismatch -->
<head>
  <meta http-equiv="Content-Language" content="en-US"> <!-- not sufficient -->
  <meta charset="utf-8">
  <title>Sample</title>
</head>
<body>
  <h1>Bienvenidos</h1> <!-- page is Spanish but html says English -->
  <p>Nuestro lema: Liberté, égalité, fraternité.</p> <!-- French not marked -->
  <p>Arabic word: مرحبا</p> <!-- RTL text without dir -->
</body>
</html>

    Quick Checklist

    • html has a lang attribute with a valid BCP 47 code.
    • If xml:lang is used on html, it exactly matches lang.
    • Inline foreign phrases have lang on the smallest relevant element.
    • Use hyphens, not underscores, in language tags (e.g., en-US).
    • Apply dir="rtl" for Arabic, Hebrew, Persian, etc., where needed.
    • Do not rely on meta Content-Language for assistive tech.
    • Validate the document and retest with a screen reader.