Use valid language codes in the `lang` attribute

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.

Use real language codes, not language names.

Why this matters and how to fix it

Why this matters

Screen readers and braille displays rely on the `lang` attribute to choose the correct pronunciation, accent, and reading rules. If the value is misspelled or not a valid BCP 47 language tag, assistive technologies may switch to the wrong language or fail to switch at all, causing words to be mispronounced and meaning to be lost.

How to fix this issue

Use valid BCP 47 language codes such as `en`, `sv-SE`, `de`, `nl-BE`, or `fr-CA`. Avoid custom or descriptive values like `english`, `us-en`, or application-specific tokens. For mixed-language content, apply `lang` attributes to the exact sections that change language.

Automated detection · Manual review recommended

Developer guidance

Invalid language codes commonly appear in CMS templates, multi-brand white-labeled sites, and localization systems that store human-readable names instead of standardized codes. Maintain a canonical language/locale map in configuration and validate `lang` attribute values during build or CI.

Code examples

Incorrect Implementation

<html lang="english"></html>

Correct Implementation

<html lang="en"></html>

Real-World Examples

Before

<html lang="us-en">
<body>
  <h1>Bienvenidos</h1>
</body>
</html>
<!-- Screen reader tries to read Spanish text using an undefined English variant → incorrect pronunciation -->

After

<html lang="es">
<body>
  <h1>Bienvenidos</h1>
</body>
</html>
<!-- Screen reader now announces Spanish correctly -->

Manual testing

  1. 1. Inspect the <html> element and confirm the `lang` value is a valid BCP 47 tag.
  2. 2. Turn on a screen reader.
  3. 3. Read the page title and first paragraph aloud.
  4. • Expected: Pronunciation matches the expected language.
  5. • Failure: Words are mispronounced or read with incorrect rhythm/accent.
  6. 4. If the page contains mixed-language content (e.g., quotes, product names, UI snippets), ensure those elements have their own `lang="xx"` attributes.
  7. 5. Run a scan with the GetWCAG automated scanner and confirm no `Invalid language code` warnings appear.
eu icon getwcag

Trusted by organizations across Europe working toward WCAG and EAA conformance