WCAG Success Criteria · Level A

WCAG 3.1.1: Language of Page

WCAG 3.1.1 requires that the default human language of each web page can be programmatically determined, primarily by setting a valid lang attribute on the HTML element. This enables assistive technologies like screen readers to pronounce content correctly and helps users with cognitive and language-based disabilities understand the page.

Level A
Wcag
Wcag 2 2 a
Understandable
Accessibility

What This Rule Means

WCAG 3.1.1 — Language of Page is a Level A success criterion under the Understandable principle. It requires that the primary human language of every web page is exposed in a way that assistive technologies can programmatically detect. In practice, this almost always means placing a valid lang attribute directly on the <html> element of the page.

The lang attribute value must be a valid BCP 47 language tag. BCP 47 tags consist of a primary language subtag (such as en for English, tr for Turkish, fr for French) and optionally a region subtag separated by a hyphen (such as en-US, tr-TR, or pt-BR). The language tag must accurately reflect the dominant language in which the page content is written. A page written primarily in Turkish must declare lang='tr' or lang='tr-TR'; a page written in English must declare lang='en' or a regional variant.

A page passes this criterion when the <html> element carries a lang attribute whose value is a non-empty, syntactically valid BCP 47 language tag that correctly identifies the page's primary language. A page fails when the lang attribute is missing entirely, when the value is empty (lang=''), or when the value is not a recognized BCP 47 language tag (for example, lang='turkish' or lang='en_US' with an underscore instead of a hyphen).

For XHTML pages served with an XML MIME type, both the lang attribute and the XML namespace attribute xml:lang should be present, and their values must match. A mismatch between the two — such as lang='en' alongside xml:lang='tr' — constitutes a failure of both this criterion and the related axe-core rule html-xml-lang-mismatch.

WCAG explicitly notes one exception: if the page is purely decorative, is a CAPTCHA that intentionally has no discernible language, or consists entirely of non-linguistic content (such as a page that is only an image with no text), it may not have a determinable language. However, this exception is narrow, and the vast majority of real-world pages contain sufficient text to require a language declaration.

Why It Matters

The primary beneficiaries of a correctly declared page language are screen reader users, the majority of whom are blind or have severe low vision. Screen readers such as NVDA, JAWS, and VoiceOver use the lang attribute to select the appropriate text-to-speech (TTS) voice and pronunciation engine. When a Turkish user visits a page that correctly declares lang='tr', their screen reader switches to a Turkish TTS voice, applying correct Turkish phonology, stress patterns, and diacritics. Without this declaration, a screen reader may default to the user's system language or to a completely incorrect language, producing gibberish-like pronunciation that makes content incomprehensible.

Consider a concrete scenario: a visually impaired Turkish citizen visits the website of a public institution to download a government form. The site omits the lang attribute. The user's NVDA installation defaults to an English TTS profile. Turkish words are read back using English phonology — words like "şehir" (city) or "başvuru" (application) become unrecognizable. The user cannot complete the form without sighted assistance, defeating the entire purpose of the digital service.

Users with cognitive and learning disabilities also benefit. Browsers use the lang attribute to offer accurate translation suggestions; some users with dyslexia rely on browser-based translation tools to convert content into a language they find easier to process. An incorrect or missing lang attribute causes these tools to misidentify the source language, producing poor translations or no offer to translate at all.

Users with motor impairments who rely on voice control software such as Dragon NaturallySpeaking depend on the software correctly interpreting the language of a page to match spoken commands to on-screen text. A misidentified page language breaks this matching.

Beyond accessibility, there are tangible SEO benefits: search engines use the lang attribute as one of several signals to determine a page's target language and region, improving the accuracy of localized search results. Correct language tagging also improves the reliability of browser spell-check and grammar-check features for all users, not only those using assistive technology. According to the World Health Organization, approximately 2.2 billion people globally have some form of vision impairment, a significant portion of whom rely on screen readers — making correct language declaration one of the highest-impact, lowest-effort accessibility improvements available.

html-has-lang — This rule checks whether the <html> element has a lang attribute at all. It flags any page where the lang attribute is completely absent from the root <html> tag, regardless of whether the attribute appears elsewhere in the document. This is one of the most common and most impactful automated catches, because the fix is a single attribute addition.
html-lang-valid — This rule checks whether the value of the lang attribute on the <html> element is a valid BCP 47 language tag. It flags values that are not recognized language codes, such as lang='turkish' (which uses the full English name instead of the ISO 639-1 code tr), lang='en_US' (which uses an underscore separator instead of a hyphen), or lang='xx' (a placeholder with no assigned language). A lang attribute that exists but contains an invalid value is just as problematic as a missing attribute, because assistive technologies cannot reliably act on it.
html-xml-lang-mismatch — This rule applies specifically to XHTML pages that carry both a lang attribute and an xml:lang attribute on the <html> element. It flags cases where the two attributes specify different language codes — for example, lang='en' and xml:lang='tr'. When these values conflict, assistive technologies and XML processors receive contradictory signals and may behave unpredictably. Both values must specify the same primary language subtag.

While these three rules cover the most common programmatic failures, automated tools cannot verify semantic accuracy — that is, they cannot determine whether the declared language actually matches the language the page is written in. A page written entirely in Turkish but declaring lang='en' will pass all three axe-core rules, yet it will still fail WCAG 3.1.1, because the declared language does not reflect the page's actual primary language. Manual review is therefore always required alongside automated scanning to confirm that the declared language is correct.

How to Test

Automated scan with axe DevTools or Lighthouse: Open the page in Chrome or Firefox. Open DevTools (F12), navigate to the axe DevTools panel or the Lighthouse tab, and run a full accessibility audit. Look specifically for violations under the rules html-has-lang, html-lang-valid, and html-xml-lang-mismatch. Axe will highlight the <html> element and describe the specific failure. Lighthouse will surface similar issues under its Accessibility category. Note all flagged violations and their recommended fixes.
Manual source inspection: View the page source (Ctrl+U in most browsers) and locate the opening <html> tag. Verify that it contains a lang attribute, that the attribute value is a valid BCP 47 tag (check against the IANA Language Subtag Registry), and that it accurately reflects the language in which the page content is written. For XHTML pages, also verify that any xml:lang attribute carries the same primary language subtag as lang.
Screen reader testing with NVDA and Firefox: Install NVDA (free, Windows) and open the page in Firefox. Press NVDA+T to read the page title and listen to the TTS voice being used. If the page is in Turkish, the voice should be a Turkish TTS voice, and Turkish words should be pronounced correctly. If you hear an English or otherwise incorrect voice on Turkish content, the lang attribute is missing or incorrect. Repeat with JAWS in Chrome and VoiceOver in Safari on macOS (Cmd+F5 to activate VoiceOver, then navigate to the page and listen to how body text is pronounced).
Browser language detection check: Open the page in Chrome. Look for the browser's built-in translation bar — Chrome will offer to translate pages it identifies as being in a foreign language relative to the browser's settings. If Chrome incorrectly identifies the page language or fails to offer translation when it should, this is a practical signal that the lang attribute is wrong or missing. This is not a definitive accessibility test, but it is a useful secondary indicator.
Semantic accuracy check (manual only): Read through the page content and confirm that the declared lang value matches the actual primary language of the page. Automated tools cannot perform this check. Pay particular attention to multilingual sites that serve different language versions from different URLs — each URL's page should declare its own correct language, not inherit a single global default.

How to Fix

Missing lang attribute — Incorrect

<!DOCTYPE html>
<html>
  <head>
    <meta charset='UTF-8'>
    <title>Başvuru Formu</title>
  </head>
  <body>
    <h1>Hoş Geldiniz</h1>
  </body>
</html>

Missing lang attribute — Correct

<!DOCTYPE html>
<html lang='tr'>
  <!-- lang='tr' tells screen readers to use a Turkish TTS voice -->
  <head>
    <meta charset='UTF-8'>
    <title>Başvuru Formu</title>
  </head>
  <body>
    <h1>Hoş Geldiniz</h1>
  </body>
</html>

Invalid lang attribute value — Incorrect

<!DOCTYPE html>
<html lang='turkish'>
  <!-- 'turkish' is not a valid BCP 47 tag; axe will flag html-lang-valid -->
  <head>
    <title>Kurumsal Site</title>
  </head>
  <body>
    <p>Şirketimiz hakkında bilgi edinmek için buraya tıklayın.</p>
  </body>
</html>

Invalid lang attribute value — Correct

<!DOCTYPE html>
<html lang='tr'>
  <!-- Use the ISO 639-1 two-letter code 'tr', not the English word 'turkish' -->
  <head>
    <title>Kurumsal Site</title>
  </head>
  <body>
    <p>Şirketimiz hakkında bilgi edinmek için buraya tıklayın.</p>
  </body>
</html>

XHTML xml:lang mismatch — Incorrect

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN'
  'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>
<html xmlns='http://www.w3.org/1999/xhtml' lang='en' xml:lang='tr'>
  <!-- lang and xml:lang disagree — html-xml-lang-mismatch violation -->
  <head><title>XHTML Sayfası</title></head>
  <body><p>İçerik burada.</p></body>
</html>

XHTML xml:lang mismatch — Correct

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN'
  'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>
<html xmlns='http://www.w3.org/1999/xhtml' lang='tr' xml:lang='tr'>
  <!-- Both lang and xml:lang are 'tr' — consistent and valid -->
  <head><title>XHTML Sayfası</title></head>
  <body><p>İçerik burada.</p></body>
</html>

Wrong language declared on a multilingual site — Incorrect

<!-- English-language version of the site, but lang is set to 'tr' globally -->
<html lang='tr'>
  <head><title>About Us</title></head>
  <body>
    <p>Welcome to our company. We specialize in accessible web solutions.</p>
  </body>
</html>

Wrong language declared on a multilingual site — Correct

<!-- Each language version declares its own correct lang attribute -->
<html lang='en'>
  <!-- This is the English page; the Turkish page at /tr/ declares lang='tr' -->
  <head><title>About Us</title></head>
  <body>
    <p>Welcome to our company. We specialize in accessible web solutions.</p>
  </body>
</html>

Common Mistakes

Using the full English name of the language instead of its BCP 47 code — writing lang='turkish', lang='english', or lang='arabic' instead of the correct codes tr, en, and ar. These values are not recognized by assistive technologies.
Using an underscore as the region separator — writing lang='en_US' or lang='tr_TR' instead of the hyphen-separated forms lang='en-US' and lang='tr-TR'. BCP 47 requires hyphens, not underscores.
Setting the lang attribute on <body> instead of <html> — the lang attribute must be on the root <html> element to satisfy axe-core's html-has-lang rule and to give assistive technologies the page-level language context they need before parsing any content.
Leaving lang as an empty string — setting lang='' is treated the same as a missing attribute by most assistive technologies and will be flagged by html-has-lang because an empty string is not a valid language tag.
Copying a template from a different language project without updating the lang attribute — a very common issue in Turkish development workflows where an English-language boilerplate is reused and the lang='en' on the <html> tag is never changed to lang='tr'.
Declaring the correct lang attribute but not updating it when launching a new language version of the site — multilingual sites that use server-side rendering must ensure the lang attribute is dynamically set per locale, not hard-coded to a single value in a shared layout template.
Assuming a CMS or framework automatically sets the lang attribute correctly — many CMS platforms (including some configurations of WordPress, Joomla, and custom frameworks) do not set a valid lang attribute by default. Developers must verify this at the template level, not assume it is handled.
Mixing up the lang attribute (for HTML) with the Content-Language HTTP header — the HTTP header affects caching and content negotiation but is not used by screen readers. The in-document lang attribute on <html> is the correct mechanism for WCAG 3.1.1 compliance.
Using a valid but incorrect regional subtag that implies a different dialect — for example, declaring lang='zh-TW' (Traditional Chinese, Taiwan) on a page written in Simplified Chinese (zh-CN) may cause a screen reader to select the wrong voice profile and pronunciation rules.
Forgetting to set lang on dynamically injected full-page content in single-page applications (SPAs) — if a SPA loads content in multiple languages within the same document shell without updating the lang attribute, users navigating between language sections will not receive correct TTS pronunciation for new content sections.

Relation to Turkey's Accessibility Regulations

WCAG 3.1.1 Language of Page carries direct legal weight in Turkey under Presidential Circular 2025/10, published in the Official Gazette No. 32933 on June 21, 2025. This circular establishes mandatory web accessibility requirements aligned with WCAG 2.2 and designates Level A conformance as the minimum obligatory standard for all covered entities.

The circular covers a broad range of both public and private sector organizations. Public institutions — including ministries, municipalities, state universities, public hospitals, and all central and local government bodies — are required to achieve full Level A conformance within one year of the circular's publication. Private sector entities covered by the regulation have a two-year compliance window and include e-commerce platforms, banks and financial institutions, private hospitals and healthcare providers, telecommunications operators with 200,000 or more subscribers, travel agencies, private transport companies, and private schools operating under authorization from the Ministry of National Education (MoNE).

Because WCAG 3.1.1 is a Level A criterion, it falls within the mandatory baseline for every entity covered by the circular. A Turkish public institution's website that omits lang='tr' from its <html> element — or that declares an incorrect or invalid language tag — is in direct non-conformance with a legally mandated standard. For private sector organizations such as banks and e-commerce platforms, the same failure within their compliance window constitutes a regulatory violation.

The practical implication for Turkish web teams is significant: every page template, every CMS layout, every SPA shell, and every dynamically generated page must be audited to confirm the presence of a valid lang='tr' (or appropriate variant) on the root HTML element. This is not merely a best-practice recommendation — under Circular 2025/10, it is a legal obligation. Given that the axe-core rules html-has-lang and html-lang-valid can detect the majority of these failures automatically, there is no technical barrier to identifying and remediating this issue before the compliance deadlines arrive.

Organizations subject to the circular should treat WCAG 3.1.1 compliance as a first-priority remediation item: it is among the easiest criteria to fix (a single attribute on a single element), yet it has an outsized impact on the accessibility of every page for screen reader users — the group whose rights the regulation is most directly designed to protect.

Bronnen & referenties

Gerelateerde artikelen

AWCAG 1.1.1: Non-text Content AWCAG 1.2.1: Audio-only and Video-only (Prerecorded)AWCAG 1.2.2: Captions (Prerecorded)