Skip to Content
International SEOIssue 104

Invalid hreflang language codes

What Is This Issue

Hreflang Tags Present

This issue checks whether your multilingual website properly declares alternate language or regional versions using hreflang tags.

What This Issue Checks

The audit verifies that pages targeting different languages or regions include hreflang tags that tell search engines which localized version to show to users based on their language and location.

What is Considered a Passing Implementation

Your website passes this check when:

  • Hreflang tags are present on pages that have alternate language/regional versions
  • Language codes follow ISO 639-1 standards (e.g., en, fr, es)
  • Regional codes follow ISO 3166-1 standards when applicable (e.g., en-US, fr-CA)
  • Hreflang URLs are valid and accessible
  • All language variants in the hreflang cluster are properly declared

Real-World Example

Passing Implementation:

<link rel="alternate" hreflang="en" href="https://example.com/en/" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr/" />
<link rel="alternate" hreflang="es" href="https://example.com/es/" />

Failing Implementation:

<!-- No hreflang tags present on a multilingual site -->
<!-- or -->
<link rel="alternate" hreflang="english" href="https://example.com/en/" />
<!-- Invalid language code: should be "en" not "english" -->

Why Is This Important

Impact on SEO

Crawlability

Without hreflang tags, search engines may not discover all language versions of your content, leading to incomplete indexing of your international pages.

Indexability

Hreflang tags help search engines understand which pages are alternate versions of each other. Without them, search engines may treat each language version as separate, unrelated pages.

Rankings

Proper hreflang implementation ensures that users in different regions see the correct language version in search results. This improves click-through rates and reduces bounce rates from users landing on incorrect language pages.

User Experience

When search engines serve the wrong language version to users, it creates a poor user experience. Users may leave immediately if they cannot understand the content, increasing bounce rates and reducing engagement signals.

Duplicate Content

Without hreflang tags, search engines may view similar content in different languages as duplicate content rather than recognizing them as alternate language versions. This can dilute your SEO efforts across languages.

AI Search / AEO

As AI-powered search becomes more prevalent, properly structured hreflang tags help AI understand your content’s language targeting, ensuring accurate representation in AI-generated answers across different languages and regions.

How Resolving This Issue Improves SEO Health Score

Fixing hreflang tag issues improves your overall SEO health score by:

  • Ensuring complete international coverage in search results
  • Reducing incorrect language version serving
  • Improving user engagement metrics from international visitors
  • Strengthening your website’s international SEO signals
  • Preventing duplicate content issues across language versions

How XeoPix Detects This

XeoPix checks whether your multilingual website properly declares hreflang tags to help search engines serve the correct language version to users.

Detection Process

XeoPix follows these logical steps to identify hreflang tag issues:

1. Check for Hreflang Tag Presence

XeoPix scans the HTML <head> section of your page to detect all hreflang declarations. It looks for:

  • <link rel="alternate" hreflang="..."> tags in the HTML
  • Hreflang declarations in HTTP Link: headers
  • Hreflang entries in XML sitemaps

2. Extract Hreflang Information

For each hreflang tag found, XeoPix extracts:

  • The language/regional code (e.g., en, fr-CA)
  • The URL being referenced
  • The source location (HTML head, HTTP header, or sitemap)

3. Validate Language and Regional Codes

XeoPix checks whether the hreflang values use proper formatting:

  • Language codes must follow ISO 639-1 (e.g., en, fr, es)
  • Regional codes must follow ISO 3166-1 when used (e.g., en-US, fr-CA)
  • Common invalid values like english, france, or en_US are flagged

4. Verify Hreflang URL Accessibility

XeoPix validates that each URL referenced in hreflang tags:

  • Is a valid URL format
  • Returns a successful HTTP status code (200-299)
  • Does not redirect to another URL
  • Is accessible to search engines

5. Count Hreflang Tags

XeoPix counts the total number of hreflang tags detected on the page to determine if any are missing.

When the Issue is Flagged

The issue is flagged when any of these conditions are met:

  • No hreflang tags detected: The page appears to be multilingual but has no hreflang declarations
  • Invalid language codes: Hreflang tags use incorrect formatting (e.g., english instead of en)
  • Broken hreflang URLs: URLs in hreflang tags return errors or redirect
  • Incomplete hreflang clusters: Not all language variants are properly declared

When the Issue Passes

The issue passes when:

  • Hreflang tags are present on multilingual pages
  • All language/regional codes follow proper ISO standards
  • All hreflang URLs are valid and accessible
  • The page includes a self-referencing hreflang tag
  • All language variants in the cluster are properly declared

How To Fix

Practical Recommendations

1. Add Hreflang Tags to All Multilingual Pages

Include hreflang tags in the <head> section of every page that has alternate language or regional versions.

Implementation:

<link rel="alternate" hreflang="en" href="https://example.com/en/" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr/" />
<link rel="alternate" hreflang="es" href="https://example.com/es/" />

2. Use Correct Language and Regional Codes

Follow ISO 639-1 for language codes and ISO 3166-1 for regional codes:

Correct format:

  • en (English)
  • fr (French)
  • en-US (English, United States)
  • fr-CA (French, Canada)

Incorrect format:

  • english (use en)
  • france (use fr)
  • en_US (use en-US with hyphen, not underscore)

3. Include Self-Referencing Hreflang Tags

Every page must include a hreflang tag that points to itself. This tells search engines that the page is aware of its place in the hreflang cluster.

Example:

<!-- On the English page -->
<link rel="alternate" hreflang="en" href="https://example.com/en/" />

4. Ensure All Hreflang URLs Are Valid

All URLs in hreflang tags must:

  • Be complete absolute URLs (including https://)
  • Return a 200 HTTP status code
  • Not redirect to another URL
  • Be accessible to search engines

5. Create Complete Hreflang Clusters

Every page in a language group should reference all other pages in that group, including itself. Don’t omit any language variants.

Example for a 3-language site:

<!-- On ALL three pages (en, fr, es) -->
<link rel="alternate" hreflang="en" href="https://example.com/en/" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr/" />
<link rel="alternate" hreflang="es" href="https://example.com/es/" />

6. Add x-default Hreflang for Language Selectors

If you have a language selector or homepage that serves as a fallback, include an x-default hreflang tag:

<link rel="alternate" hreflang="x-default" href="https://example.com/" />

Priority Order

  1. First: Add missing hreflang tags to all multilingual pages
  2. Second: Fix invalid language/regional codes
  3. Third: Ensure all hreflang URLs are valid and accessible
  4. Fourth: Add self-referencing tags and complete the hreflang clusters

What We Store

Storage Level

Page Level

Database Table / Prisma Model

PageInternationalSeo

Stored Fields

FieldTypeDescription
hreflangTagsJson?The hreflang tags found on the page
invalidLangCodesString[]Invalid language codes detected

Detection Dependencies

  • HTML Document
  • HTTP Response Headers

Examples

Example 1: Missing Hreflang Tags on a Multilingual Site

Scenario

A website serves content in English, French, and Spanish with separate pages for each language.

Problematic State (Fails)

<!-- On page: https://example.com/about/ -->
<!-- No hreflang tags present despite having multilingual content -->

Result: Search engines don’t know the page has alternate language versions. Users may see the wrong language in search results.

Corrected State (Passes)

<!-- On page: https://example.com/about/ -->
<link rel="alternate" hreflang="en" href="https://example.com/en/about/" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr/about/" />
<link rel="alternate" hreflang="es" href="https://example.com/es/about/" />

Result: Search engines understand the language relationships and serve the correct version to each user.

Example 2: Invalid Hreflang Language Codes

Scenario

A website uses incorrect formatting for hreflang language codes.

Problematic State (Fails)

<link rel="alternate" hreflang="english" href="https://example.com/en/" />
<link rel="alternate" hreflang="french" href="https://example.com/fr/" />
<link rel="alternate" hreflang="en_US" href="https://example.com/en/" />

Result: Search engines ignore these hreflang declarations because the language codes are invalid.

Corrected State (Passes)

<link rel="alternate" hreflang="en" href="https://example.com/en/" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr/" />
<link rel="alternate" hreflang="en-US" href="https://example.com/en/" />

Result: Search engines correctly interpret the language and regional targeting.

Example 3: Broken Hreflang URLs

Scenario

Hreflang tags reference URLs that return errors or redirect.

Problematic State (Fails)

<link rel="alternate" hreflang="en" href="https://example.com/en/" />
<link rel="alternate" hreflang="fr" href="https://example.com/french/" />
<!-- The /french/ URL returns a 404 error -->

Result: Search engines may ignore the entire hreflang cluster due to invalid references.

Corrected State (Passes)

<link rel="alternate" hreflang="en" href="https://example.com/en/" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr/" />
<!-- Both URLs return 200 OK status -->

Result: Search engines can successfully crawl and understand all language variants.

Unit Test

Test File

__tests__/seo-audit-checks/internationalSeo/issue-12-hreflang-multi-language.test.js

Purpose

This unit test validates that the HREFLANG_MULTI_LANGUAGE issue is correctly detected when a page declares multiple language hreflang tags, indicating a multilingual site.

Tested Function

runInternationalSeo(ctx) from toggleGroups/internationalSeo.js

Issue Information

  • Issue Number: 12
  • Issue Code: hreflang_multi_language
  • Toggle Group: internationalSeo

Test Scenarios

Positive Test Cases

  • Should not detect HREFLANG_MULTI_LANGUAGE when only one language hreflang tag is present
  • Should not detect HREFLANG_MULTI_LANGUAGE when only x-default and one language hreflang tag exist (x-default is not counted as a language)
  • Should not detect issue when no hreflang tags exist at all

Negative Test Cases

  • Should detect HREFLANG_MULTI_LANGUAGE when multiple language hreflang tags (en, es, fr) are present
  • Should detect HREFLANG_MULTI_LANGUAGE with exactly two languages (boundary)

Boundary Cases

  • Exactly two language hreflang tags — the minimum threshold for multi-language detection

Edge Cases

  • Empty HTML: No hreflang tags in the document — should not detect the issue
  • Malformed HTML: Partially malformed markup alongside valid hreflang tags — should handle gracefully without throwing and still detect the issue

Expected Outcome

Pass

The issue should be reported when the page contains two or more language-specific hreflang tags (excluding x-default).

Fail

The issue should not be reported when:

  • Only one language hreflang tag is present
  • Only x-default and one language tag exist
  • No hreflang tags exist at all

Validation

The unit test verifies:

  • Correct issue detection when multiple languages are present
  • No issue detection for single-language or no-hreflang scenarios
  • x-default is excluded from the language count
  • Graceful handling of malformed HTML without throwing
  • Correct issue code assignment
  • toggleGroups/internationalSeo.js — contains runInternationalSeo()
  • issueCodes.js — defines HREFLANG_MULTI_LANGUAGE issue code constant

Coverage Summary

  • Covers single-language, dual-language, and multi-language scenarios
  • Verifies x-default exclusion from language counting
  • Includes empty HTML and malformed HTML edge cases
  • Confirms correct issue code and metadata presence

References

Last updated on
Issue 103Issue 105