WCAG 3.1.1 Language of Page: How to Set the Correct HTML Language

WCAG 3.1.1 Language of Page: How to set the correct HTML language

WCAG 3.1.1 (Language of Page) requires web pages to identify their primary language so assistive technologies can present text correctly. This short guide shows the exact HTML, server headers and simple checks you need to meet the criterion and help users who rely on screen readers or text-to-speech.

What the success criterion covers

The criterion asks that the default language of each web page be programmatically determinable. That normally means setting the language on the root element and marking any passages that use a different language. If your page is served as XHTML, you may need to use xml:lang too.

Set the language on the root element

Add a BCP 47 language tag to the html element. For British English use:

<html lang=“en-GB”>

For general English without a region, use:

<html lang=“en”>

Why BCP 47 tags matter: screen readers use them to select pronunciation rules and voice variants. Common tags include en, en-GB, fr, es, de. Use the most specific tag you can when regional pronunciation or vocabulary matters.

When content contains multiple languages

If a section is in another language, mark it on an element that encloses that content. For short phrases use a span. For longer blocks use a paragraph or section element.

<p lang=“fr”>Bonjour. </p>

<span lang=“es”>Hola</span>, this sentence is mostly English.

XHTML and xml:lang

If you deliver pages as application/xhtml+xml, include xml:lang as well as lang on the same element. Example:

<html lang=“en” xml:lang=“en” xmlns=“http://www.w3.org/1999/xhtml">

That prevents ambiguity for XML processors and older assistive tech that check xml:lang.

Content-Language HTTP header

Sending a Content-Language header from the server can be useful. If you use it, make sure the header matches the lang attribute in the HTML. The header alone does not replace a lang attribute because browsers and many assistive technologies read the DOM attribute first.

Single page apps and dynamic content

For single page apps update the document language whenever the primary language changes. Use JavaScript to set the html lang attribute at runtime.

Example:

document.documentElement.lang = ‘fr-FR’;

If users switch language with a control, update the lang attribute when the switch happens. Also update any server headers if a full page reload occurs.

Programmatic detection and user overrides

Automatic language detection can help, but it is not perfect. Offer a clear language selector so users can correct the detected language. Do not rely solely on automatic detection to meet WCAG 3.1.1.

Common implementation mistakes

• Forgetting to set the root lang when templating or using a CMS. The default empty attribute means no programmatic language is available.
• Using incorrect or non-BCP-47 tags such as proprietary abbreviations. Use standard tags like en-GB or fr-CA.
• Marking only visible headings but not the root element. Assistive tech will still use the root language if present.
• Relying solely on the Content-Language header and leaving the HTML without lang.

How to test

1. Open view-source or inspector and confirm the html element has a lang attribute set to the correct BCP 47 tag.
2. Locate any passages in another language and confirm they have a lang attribute on an enclosing element.
3. For XHTML responses check xml:lang is present on the html element.
4. Run an automated checker such as axe or WAVE to catch missing or inconsistent lang attributes, then do a manual check with a screen reader if available.

Practical checklist before launch

• Root html element contains a valid BCP 47 tag matching the page language.
• All non-default language passages are marked with lang on an element that wraps the passage.
• XHTML pages include xml:lang on the html element.
• SPA updates document.documentElement.lang when language changes.
• Content-Language header, if used, matches the html lang attribute.
• Provide a visible language selector so users can override automatic choices.

Examples table

Situation	HTML to use
British English page	<html lang=“en-GB”>
Page mostly English with one Spanish sentence	<p lang=“es”>Buenos días</p>
XHTML document	<html lang=“de” xml:lang=“de” xmlns=“http://www.w3.org/1999/xhtml">

Final notes

Setting the language is a low effort change with a big benefit. It helps screen readers choose the right pronunciation, improves machine translation accuracy and reduces confusion for multilingual users. Make the lang attribute part of your page template and verify it in your build and runtime tests.