lang and xml:lang values must match

WCAG 3.1.1
Language of Page

Content available in English only.

Accessibility isn’t just about avoiding violations — it’s about ensuring that everyone can use your product with confidence. This guide explains each rule’s intent, highlights common issues, and shows how to fix them according to WCAG and the European Accessibility Act (EAA).

These guidelines do not replace the official WCAG standards. They’re concise, developer-focused notes to help you identify and fix issues effectively.

If you use both `lang` and `xml:lang`, they must always match.

Why this matters and how to fix it

Why this matters

Some assistive technologies read language from `lang`, while others (especially those processing XML-based formats such as EPUB, XHTML, or PDF generators) use `xml:lang`. If the two values differ, pronunciation rules become unpredictable — leading to mispronunciation, incorrect braille translation, and inconsistent reading experiences.

How to fix this issue

When both `lang` and `xml:lang` are present, they must be set to the same valid BCP 47 language code. Ideally, drive both values from the same locale source so they remain synchronized.

Automated detection · Manual review recommended

Developer guidance

This issue is common in systems that output both HTML and PDF/XHTML (CMS platforms, enterprise apps, documentation sites). Ensure the language is not hardcoded in templates. Instead, define it once in your localization config and apply it to both `lang` and `xml:lang` during rendering.

Code examples

Incorrect Implementation

<html lang="en" xml:lang="fr">…</html>

Correct Implementation

<html lang="en" xml:lang="en">…</html>

Real-World Examples

Before

<html lang="sv" xml:lang="en">
<body>
  <h1>Rapport</h1>
</body>
</html>
<!-- Screen readers may switch between English and Swedish pronunciation unexpectedly -->

After

<html lang="sv" xml:lang="sv">
<body>
  <h1>Rapport</h1>
</body>
</html>
<!-- Consistent pronunciation across assistive technologies -->

Manual testing

  1. 1. Inspect the <html> tag and confirm whether both `lang` and `xml:lang` are present.
  2. 2. If both appear, verify they match exactly and are valid BCP 47 codes.
  3. 3. Turn on a screen reader and listen to the first heading.
  4. • Expected: Pronunciation matches the intended language.
  5. • Failure: Words sound mispronounced or in the wrong accent.
  6. 4. If the site outputs PDFs, EPUB, or XHTML templates, test generated exports—incorrect xml:lang often only appears in exports.
  7. 5. Run W3C Internationalization Checker to confirm no mixed-language declaration warnings.
eu icon getwcag

Trusted by organizations across Europe working toward WCAG and EAA conformance