Hreflang Builder

Build and validate hreflang tags for international SEO

URL Mapping

CSV with columns: url, locale, group_id
CSV Format Requirements

Your CSV should have these columns: url, locale, group 

url,locale,group
https://example.com/en/page,en,page1
https://example.com/fr/page,fr,page1
https://example.com/es/page,es,page1
URLs with the same "group" value are alternate versions of each other

Build Options

Check for errors (duplicate locales, missing return links, etc.)
Generate HTML tags and/or XML sitemap
Comma-separated list of locales that should exist for all groups (e.g., en-US,es-ES,fr-FR)

Locale Format

  • Language only: en, fr
  • Language + Region: en-US, fr-FR
  • X-default: Fallback for unmatched locales

Important

Hreflang tags must be bidirectional. Every URL must reference all its alternates, including itself.

Hreflang Builder Tutorial

What are hreflang Tags?

Hreflang tags tell search engines about language and regional variations of your pages. They help Google serve the correct language/regional URL to users based on their location and language settings.

How to Use This Tool:

  1. Prepare a CSV file with three columns:
    • url: The full URL of the page
    • locale: Language/region code (e.g., en, en-US)
    • group: Identifier linking alternate versions (same group = alternates)
  2. Upload the CSV file
  3. Enable validation mode to check for errors
  4. Choose output format (HTML link tags or XML sitemap)
  5. Optionally specify expected locales for validation
  6. Click "Generate hreflang Tags"
  7. Review validation report and download generated tags

Locale Code Format:

Format Example When to Use
Language only en, fr, es Content targets a language without regional specificity
Language + Region en-US, en-GB, fr-FR Content is regionally specific (US English vs UK English)
X-default x-default Fallback URL when no locale matches user's preference

Common Validation Errors:

  • Missing reciprocal link: URL A links to URL B, but URL B doesn't link back to URL A
  • Duplicate locale codes: Same locale code used twice within a URL group
  • Invalid language code: Language code doesn't follow ISO 639-1 standard
  • Missing self-reference: URL doesn't include itself in its hreflang annotations
  • Incomplete group: URL group missing expected locales

Example CSV File:

url,locale,group
https://example.com/en/about,en,about-page
https://example.com/fr/a-propos,fr,about-page
https://example.com/es/acerca-de,es,about-page
https://example.com/en/products,en,products-page
https://example.com/fr/produits,fr,products-page
https://example.com/es/productos,es,products-page

Output Formats:

Format Implementation Best For
HTML Link Tags Add <link rel="alternate"> tags to page <head> Small sites with few language versions
XML Sitemap Include <xhtml:link> annotations in sitemap Large sites, easier maintenance

Best Practices:

  • Be bidirectional: Every URL must reference all its alternates, including itself
  • Use x-default: Specify a fallback URL for unmatched locales/languages
  • Self-reference: Always include the current page's own hreflang tag
  • Consistent implementation: Use HTML OR sitemap, not both (Google will prioritize sitemap if both exist)
  • Validate regularly: Check for errors after adding new pages or locales
  • Keep groups complete: If you have 5 locales, every URL group should ideally have 5 URLs
HTML Tags vs XML Sitemap - Which Should I Use?

HTML Link Tags:

  • ✅ More visible, easier to debug
  • ✅ Works without XML sitemap
  • ❌ Harder to maintain for large sites
  • ❌ Requires updating every page template

XML Sitemap:

  • ✅ Centralized, easier to maintain
  • ✅ Better for large sites with many locales
  • ✅ Automatically updated when regenerating sitemap
  • ❌ Less visible, harder to debug