Page language and the ADA

One attribute that decides how a page sounds

Screen readers, braille software, translation tools and caption displays all need to know what language the page is written in. WCAG 2.1 success criterion 3.1.1 asks that the default human language of each web page can be programmatically determined. For HTML that means a valid lang attribute on the html element. For PDF it means the language set in the document properties.

Without it, a screen reader falls back to the user's default voice. Spanish text is read with English pronunciation rules and becomes nearly unintelligible. A person with dyslexia using text-to-speech, or someone relying on a braille translation table, has the same problem.

Bilingual portals and the ADA angle

Many public agencies publish the same service in English and Spanish, and sometimes in several more languages. The common failure is a Spanish page generated from an English template whose lang="en" never changes. The page looks perfect to a sighted reader and sounds wrong to everyone using speech. Language is also easy for a scanner to confirm and easy for a person to miss. PDFs need a language too; see documents and PDFs.

Markup examples: portal pages, templates and routes

Spanish page for a DMV appointment

<!DOCTYPE html>
<html>
<head><title>Programe su cita</title></head>
<body>…Programe su cita en el DMV…</body>
</html>

<!DOCTYPE html>
<html lang="es">
<head><title>Programe su cita</title></head>
<body>…Programe su cita en el DMV…</body>
</html>

Invalid language codes

<html lang="english">
<html lang="en_US">
<html lang="us">

<html lang="en">
<html lang="en-US">
<!-- subtag after the hyphen is a region; "us" is not a language -->

A shared layout that hard-codes the language

<!-- layout.html used for every locale -->
<html lang="en">
  <body>{{ content }}</body>
</html>

<!-- layout.html -->
<html lang="{{ page.locale }}">   <!-- "en", "es", "vi", "zh-Hans" -->
  <body>{{ content }}</body>
</html>

Single-page app that switches language without a reload

function setLocale(code) {
  loadStrings(code);
  render();
}

function setLocale(code) {
  loadStrings(code);
  document.documentElement.lang = code;
  render();
}

Native apps and PDFs

Native apps take their language from the device locale and from the localized resources you ship, so the equivalent work is providing full translations rather than adding an attribute. For PDFs, set the document language in the file properties (the /Lang entry in the catalog) when you export.

Verify it

1. View source or use developer tools and confirm html lang on one page in each language.
2. Open the page in a screen reader. Listen for the right voice; a wrong accent is the fastest way to notice a missing or incorrect value.
3. Run the language through a BCP 47 checker if you use unusual codes such as zh-Hant-TW.
4. Tools: automated tests reliably detect a missing or invalid lang. They cannot tell you the page is Spanish while the attribute says English, so spot-check translated pages by reading.

Recurring errors

• The attribute is present on body or on a wrapper div, not on html.
• An empty value, lang="".
• A default language set in the CMS that nobody changes when a translation is created.
• Redirect or error pages (404, session timeout) that have no lang at all.

Ship it when

• Every page template emits lang on html using the page's actual language.
• Translated versions set it dynamically, including error pages.
• Exported PDFs have a language set in the properties.

Sources

• Understanding SC 3.1.1: Language of Page (W3C), opens in a new tab
• 28 CFR Part 35, Subpart H: Accessibility of Web Information and Services (eCFR), opens in a new tab

Standard version: WCAG 2.1 (W3C Recommendation, 5 June 2018), as named in the Title II web rule. This page is for informational purposes only and is not legal advice. For binding requirements, refer to the official ADA statute and regulations, and ask a lawyer how they apply to you.