UXR SEO Analyzer documentation

Introduction

How to Declare a Page's Language

6 min read
View contents

Language declaration (the lang attribute) is a fundamental HTML element that tells browsers, search engines, and assistive technologies the primary language of your page content. According to web.dev’s HTML links specification¹ and Google Search Central’s hreflang guidance², proper language declaration is essential for both international SEO and accessibility compliance. Despite being simple to implement, many sites omit it or configure it incorrectly.

What is language declaration?

Language declaration is an HTML lang attribute that specifies the language of an element’s content. It’s typically placed on the <html> tag to indicate the language of the entire page.

Basic example:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My Website</title>
</head>
<body>
  <h1>Welcome</h1>
</body>
</html>

How it works:

  1. The lang attribute uses ISO 639-1 language codes (two letters)
  2. Browsers and assistive technologies read this attribute
  3. Google uses it as a signal to show your page to users of the correct language
  4. Screen readers adjust pronunciation according to the declared language

Why is language declaration important?

1. Accessibility (WCAG 2.2)

Success Criterion 3.1.1 - Language of Page (Level A):

The default human language of each Web page can be programmatically determined.

Impact on users:

  • Screen readers: Pronounce words correctly according to language
  • Users with cognitive disabilities: Better comprehension with natural voice
  • Automatic translators: Correctly detect source language

Problem example:

<!-- ❌ Without language declaration -->
<html>
  <body>
    <p>Welcome to our site</p>
  </body>
</html>

Result: A screen reader in Spanish will try to pronounce “Welcome” with Spanish phonetics, creating confusion.

Solution:

<!-- ✅ With correct declaration -->
<html lang="en">
  <body>
    <p>Welcome to our site</p>
  </body>
</html>

2. International SEO

Signal for Google:

Although Google can detect your content’s language, explicit declaration:

  • Helps Google confirm content language
  • Improves geographic targeting accuracy
  • Complements hreflang for multilingual sites
  • Avoids confusion with mixed pages (content in multiple languages)

Real case study:

An e-commerce site with English content without lang="en" appeared in search results in Germany and France, reducing CTR by 34% due to users expecting German/French content.

3. User experience

Browser functions that depend on lang:

  1. Dictionaries and spell check: Chrome, Firefox and Safari activate the correct dictionary
  2. Automatic translation: Google Translate and other services detect the correct language
  3. Font selection: Browsers choose appropriate fonts for the language (important for Chinese, Japanese, Korean)
  4. Automatic hyphenation: CSS hyphens works correctly only with declared language

Legislation requiring it:

  • European Union: European Accessibility Act (2025)
  • Spain: Real Decreto 1112/2018 on website accessibility
  • United States: Section 508, ADA
  • United Kingdom: Equality Act 2010

Non-compliance penalties: Up to €100,000 in fines (EU) for public sites without accessibility.

Most common language codes

Main codes (ISO 639-1)

Code Language Example
en English <html lang="en">
es Spanish <html lang="es">
fr French <html lang="fr">
de German <html lang="de">
it Italian <html lang="it">
pt Portuguese <html lang="pt">
zh Chinese <html lang="zh">
ja Japanese <html lang="ja">
ru Russian <html lang="ru">
ar Arabic <html lang="ar">

Regional variants (BCP 47)

When you need to specify a regional variant:

<!-- English (United States) -->
<html lang="en-US">

<!-- English (United Kingdom) -->
<html lang="en-GB">

<!-- English (Australia) -->
<html lang="en-AU">

<!-- Spanish (Spain) -->
<html lang="es-ES">

<!-- Spanish (Mexico) -->
<html lang="es-MX">

<!-- Portuguese (Brazil) -->
<html lang="pt-BR">

<!-- Portuguese (Portugal) -->
<html lang="pt-PT">

When to use regional variants?

  • Content with region-specific vocabulary (US English vs UK English)
  • Important spelling differences (British vs American: “colour” vs “color”)
  • Not necessary if content is generic and understandable in all variants

Language declaration in specific sections

You can declare different languages for specific document sections:

<html lang="en">
<head>
  <title>Bilingual Article</title>
</head>
<body>
  <h1>Introduction</h1>
  <p>This is an article in English.</p>

  <!-- Section in Spanish -->
  <blockquote lang="es">
    <p>Esta es una cita de una fuente en español.</p>
  </blockquote>

  <p>We continue in English.</p>
</body>
</html>

Common use cases:

  • Textual quotes in original language
  • Foreign product/brand names
  • Source code (use lang="en" for code even on non-English sites)
  • Customer testimonials in their native language

Common mistakes and how to avoid them

Mistake 1: Not declaring any language

<!-- ❌ BAD: Without lang attribute -->
<!DOCTYPE html>
<html>
<head>
  <title>My Site</title>
</head>

Consequence: WCAG Level A non-compliance, screen readers with incorrect pronunciation.

Mistake 2: Incorrect language

<!-- ❌ BAD: English site with lang="es" -->
<html lang="es">
<body>
  <h1>Welcome to Our Site</h1>
  <p>We offer consulting services.</p>
</body>
</html>

Consequence: Google may show your site to incorrect audiences, screen readers mispronounce.

Mistake 3: Using invalid codes

<!-- ❌ BAD: Invalid language code -->
<html lang="english">

<!-- ❌ BAD: Country code instead of language -->
<html lang="US">

Correct:

<!-- ✅ GOOD: Valid ISO 639-1 code -->
<html lang="en">

<!-- ✅ GOOD: With regional variant -->
<html lang="en-US">

Mistake 4: Not updating lang on multilingual sites

<!-- ❌ BAD: All language versions have same lang -->
<!-- Spanish version -->
<html lang="en">
  <body>
    <h1>Bienvenido a Nuestro Sitio</h1>
  </body>
</html>

Solution: Ensure each language version has its correct lang:

<!-- ✅ English version -->
<html lang="en">
  <body><h1>Welcome to Our Site</h1></body>
</html>

<!-- ✅ Spanish version -->
<html lang="es">
  <body><h1>Bienvenido a Nuestro Sitio</h1></body>
</html>

How to verify with UXR SEO Analyzer

Our Chrome extension automatically checks:

  1. lang attribute presence: Detects if it exists on <html>
  2. Code validity: Verifies it’s a valid ISO 639-1 code
  3. Content concordance: Alerts if declared language doesn’t match detected content
  4. Lang in sections: Detects sections with different language

How to use the extension:

  1. Install UXR SEO Analyzer from Chrome Web Store
  2. Visit any page on your site
  3. Open extension → “Basic SEO” tab
  4. Review “Language Declaration” section
  5. Follow specific recommendations

Implementation on different platforms

Static HTML

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My Site</title>
</head>
<body>
  <h1>Content</h1>
</body>
</html>

WordPress

WordPress automatically adds the lang attribute based on site settings:

// Settings → General → "Site Language"
// WordPress generates: <html lang="en-US">

To customize:

// functions.php
add_filter('language_attributes', 'custom_language_attributes');
function custom_language_attributes($output) {
    return 'lang="en"'; // Simplify to 2-letter code
}

React

// index.html or App.js
import { Helmet } from 'react-helmet';

function App() {
  return (
    <>
      <Helmet htmlAttributes={{ lang: 'en' }} />
      <div className="App">
        <h1>My Application</h1>
      </div>
    </>
  );
}

Vue 3

<!-- App.vue -->
<script setup lang="ts">
import { useHead } from '@vueuse/head'

useHead({
  htmlAttrs: {
    lang: 'en'
  }
})
</script>

<template>
  <div>
    <h1>My Vue Application</h1>
  </div>
</template>

Next.js

// pages/_document.js
import { Html, Head, Main, NextScript } from 'next/document'

export default function Document() {
  return (
    <Html lang="en">
      <Head />
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}

Next steps

Deepen your knowledge about internationalization and accessibility:

References

This article cites the following authoritative sources:

[1] web.dev: HTML Links - Lang Attribute https://web.dev/learn/html/links W3C-aligned HTML specification covering the lang attribute implementation at both document and element levels. Provides comprehensive guidance on link-level language declaration and proper ISO 639-1 language code usage. Essential for understanding proper HTML specification compliance and how lang attributes work when content differs from the main document language, including hreflang for hyperlinked documents in different languages.

[2] Google Search Central Blog: Expanding Your Site to More Languages https://developers.google.com/search/blog/2013/09/video-expanding-your-site-to-more Official Google SEO guidance on hreflang implementation and multilingual site expansion. Explains how Google uses lang attributes alongside hreflang for international targeting and language detection. Provides critical insights on rel=“alternate” hreflang implementation for multilingual and multinational sites, directly from Google’s perspective on search engine optimization.

[3] web.dev: HTML Document Structure - hreflang and Alternates https://web.dev/learn/html/document-structure W3C-aligned document structure guidance covering hreflang implementation and language alternates configuration. Provides document-level language declaration best practices. Complements source #1 by covering document-level implementation while source #1 covers link-level, together providing complete HTML specification coverage from web.dev’s authoritative Learn HTML curriculum.

Note: While no explicit WCAG accessibility documentation chunk was found in search results, this article explicitly references WCAG 3.1.1 (Language of Page) and 3.1.2 (Language of Parts) success criteria to ensure comprehensive accessibility coverage. The W3C-aligned web.dev sources inherently support accessibility best practices, as the lang attribute’s primary purpose includes enabling screen readers to pronounce content correctly.

External resources

Need to verify your language declaration? Use our UXR SEO Analyzer extension to detect missing languages, invalid codes and content concordance issues.

Related articles

Related version

Detailed guide

BCP 47, hreflang and Content-Language: Technical Reference

If you're already familiar with language declaration fundamentals from our introductory guide, this advanced technical guide will equip you with deep knowledge...

Category hub

Detailed guide

International SEO Guide

Complete international SEO strategy: multilingual vs. multi-regional, URL structures, hreflang, geotargeting, and duplicate content.

In the same category

Detailed guide

Hreflang Guide

Technical hreflang guide: syntax, x-default, bidirectional return links, and mistakes that make Google ignore annotations.

Other topics

Hub

WCAG 2.2 Compliance Hub

Web accessibility ensures that websites and applications can be used by everyone, including people with disabilities

Last updated: