--- title: "Spanish hreflang: Write and check your HTML tags." description: "Add Spanish and English alternate tags, check ISO codes, self-canonicals, and return links, then audit your implementation with a crawler." canonical: "https://scalewithsearch.com/articles/hreflang-implementation-guide" date: "2026-03-20" modified: "2026-09-25" --- ## Site navigation - [Scale With Search](https://scalewithsearch.com/) - Real estate - Real estate - [Real estate](https://scalewithsearch.com/for/real-estate) - Work - Start here - [Send your brief](https://scalewithsearch.com/work#send-your-brief) - [Prepare your six-question brief](https://scalewithsearch.com/work#prepare-your-six-question-brief) - Build - [Site build, content library with SEO, signal desk](https://scalewithsearch.com/work) - For your business - Trades and home services - [Auto body and collision shops](https://scalewithsearch.com/for/auto-body-and-collision-shops) - [Foundation and home repair contractors](https://scalewithsearch.com/for/foundation-and-home-repair) - [Garage door and fencing contractors](https://scalewithsearch.com/for/garage-door-and-fencing-contractors) - [HVAC contractors](https://scalewithsearch.com/for/hvac-contractors) - [Janitorial and commercial cleaning companies](https://scalewithsearch.com/for/janitorial-and-commercial-cleaning) - [Locksmiths](https://scalewithsearch.com/for/locksmiths) - [Moving companies](https://scalewithsearch.com/for/moving-companies) - [Pest control companies](https://scalewithsearch.com/for/pest-control-companies) - [Plumbing and electrical contractors](https://scalewithsearch.com/for/plumbing-and-electrical-contractors) - [Restoration and water or fire damage companies](https://scalewithsearch.com/for/restoration-and-water-fire-damage) - [Roofing companies](https://scalewithsearch.com/for/roofing-companies) - [Towing companies](https://scalewithsearch.com/for/towing-companies) - [Tree services and landscaping companies](https://scalewithsearch.com/for/tree-services-and-landscaping) - [Solar installers](https://scalewithsearch.com/for/solar-installation) - [General contractors](https://scalewithsearch.com/for/general-contractors-and-construction) - [Paving, concrete, and flooring contractors](https://scalewithsearch.com/for/paving) - Practices and professional services - [Bookkeeping and tax practices](https://scalewithsearch.com/for/bookkeeping-and-tax-practices) - [Dental practices](https://scalewithsearch.com/for/dental-practices) - [Family and criminal defense law firms](https://scalewithsearch.com/for/family-and-criminal-defense-law-firms) - [Med spas and aesthetics practices](https://scalewithsearch.com/for/med-spas-and-aesthetics) - [Personal injury law firms](https://scalewithsearch.com/for/personal-injury-law-firms) - [Veterinary clinics](https://scalewithsearch.com/for/veterinary-clinics) - [Gyms and fitness studios](https://scalewithsearch.com/for/fitness) - [Therapy and outpatient health practices](https://scalewithsearch.com/for/therapy-and-outpatient-health) - [Medical billing companies](https://scalewithsearch.com/for/medical-billing) - [Insurance agencies](https://scalewithsearch.com/for/insurance-agencies) - [Financial advisors](https://scalewithsearch.com/for/financial-advisors) - [Property management companies](https://scalewithsearch.com/for/property-management) - [Recruiting and staffing agencies](https://scalewithsearch.com/for/recruiting-and-staffing) - [Architects and interior designers](https://scalewithsearch.com/for/architects-and-interior-designers) - [Logistics and supply chain companies](https://scalewithsearch.com/for/logistics-and-supply-chain) - Agencies, MSPs, and manufacturing - [IT and managed service providers](https://scalewithsearch.com/for/it-and-managed-service-providers) - [Machine shops and precision manufacturers](https://scalewithsearch.com/for/machine-shops-and-precision-manufacturing) - [Marketing agencies and freelancers](https://scalewithsearch.com/for/marketing-agencies-and-freelancers) - [SEO agencies and consultants](https://scalewithsearch.com/for/seo-agencies-and-consultants) - [Small manufacturers and fabricators](https://scalewithsearch.com/for/small-manufacturers-and-fabricators) - Restaurants, shops, studios, and nonprofits - [Restaurants and hospitality businesses](https://scalewithsearch.com/for/restaurants-and-hospitality) - [Retail stores and ecommerce sellers](https://scalewithsearch.com/for/retail-and-ecommerce) - [Photographers, event planners, and travel agents](https://scalewithsearch.com/for/photographers) - [Churches and nonprofits](https://scalewithsearch.com/for/churches-and-nonprofits) - [All industries](https://scalewithsearch.com/for/) - Learn - For your office - [Office job guides](https://scalewithsearch.com/guides/) - [Browser calculators](https://scalewithsearch.com/tools/) - Start here - [How it works](https://scalewithsearch.com/how-it-works) - [Free Starter Kit](https://scalewithsearch.com/kit/business-memory-starter-kit.zip) - [Synthetic specimen](https://scalewithsearch.com/specimen/working-session-specimen.zip) - Guides - [The Complete Guide to Business Memory for AI Agents](https://scalewithsearch.com/articles/business-memory-for-ai-agents-guide) - [The Complete Small-Business Guide to AI Agent Governance](https://scalewithsearch.com/articles/ai-agent-governance-guide-small-business) - [The Complete Guide to Leaving Vendor AI Memory](https://scalewithsearch.com/articles/leaving-vendor-ai-memory-guide) - Articles by cluster - [Business memory](https://scalewithsearch.com/articles/business-memory-for-ai-agents-guide) - [Agent governance](https://scalewithsearch.com/articles/ai-agent-governance-guide-small-business) - [Migration and ownership](https://scalewithsearch.com/articles/leaving-vendor-ai-memory-guide) - For machines - [llms.txt](https://scalewithsearch.com/llms.txt) - [llms-full.txt](https://scalewithsearch.com/llms-full.txt) - [Machine view](https://scalewithsearch.com/?view=machine) - Company - Evidence - [Proof](https://scalewithsearch.com/proof) - Company - [About](https://scalewithsearch.com/about) # Implement hreflang so each searcher lands on the right language version. A shop sells in the United States and Spain. A customer in Madrid searches in Spanish and lands on the English product page with prices in dollars. She leaves. The Spanish page exists, but nothing told Google which version belongs to which searcher. Hreflang is an HTML attribute that tells Google which language and regional versions of a page exist. Google uses it to show each searcher the version in their language or for their region. Google does not treat a translation as duplicate content, but it can show the wrong version when hreflang is missing or broken. Many international sites implement hreflang wrongly, or not at all. This article covers the syntax, the three delivery methods, the common mistakes, platform code, and validation. ## Decide whether you need hreflang Use hreflang in three cases: - You have the same page in more than one language, such as English, Spanish, and French. - You have regional variants of one language, such as US English, UK English, and Australian English. - You serve different content by country, such as prices in US dollars or euros, or different shipping terms. You do not need hreflang if you have one language and one region. You also do not need it for separate sites on separate topics. Hreflang connects equivalent pages. If two pages cover different topics, do not connect them with hreflang. If your US and UK English pages are identical, you do not need two URLs. Use one URL. If they differ in spelling, currency, or shipping, use two URLs and connect them with hreflang. ## Write the tags correctly ### Use the basic format ```html ``` For example: ```html ``` Use absolute URLs, with the protocol and the host. ### Use ISO codes The language code comes from ISO 639-1 and has two letters. Common codes are `en` (English), `es` (Spanish), `fr` (French), `de` (German), `it` (Italian), `pt` (Portuguese), `zh` (Chinese), `ja` (Japanese), and `ko` (Korean). The optional region code comes from ISO 3166-1 alpha-2 and also has two letters. Common codes are `US`, `GB`, `CA`, `AU`, `ES`, `MX`, `FR`, and `DE`. The code for the United Kingdom is `GB`, not `UK`. Hreflang values are not case-sensitive, so `en-gb` and `en-GB` are equal. A region code alone is not valid. You must always give the language, and you can add a region after it. ### Choose language-only or language-region A language-only tag applies to every region that speaks that language: ```html ``` Use it when the content is the same for all English speakers. A language-region tag applies to one region: ```html ``` Use it when the content differs by region: prices, shipping, spelling, or terminology. Be as specific as the content requires, and no more. ### Add x-default as the fallback ```html ``` The `x-default` value names the page for searchers who match none of your languages or regions. Suppose a user searches in Japanese, and you have English, Spanish, and French. The `x-default` page receives that user. Point it at a language selector page or at your primary language version. It is optional, but add it. ## Choose one delivery method Google accepts hreflang in three places: HTML tags, the XML sitemap, and HTTP headers. Google treats the three methods as equal. Pick one method for each page and do not mix them, because conflicting values cause errors. ### HTML tags in the head Add the tags to the `` of each page. Each page must list itself and every alternate, plus `x-default`. The English page: ```html ``` The Spanish page carries the same four tags. Hreflang works in both directions. If the English page names the Spanish page, the Spanish page must name the English page. Google ignores a link that has no return link. ### XML sitemap The sitemap method suits large sites. One central file is easier to maintain than tags in every template, and the page HTML stays smaller. With 10 languages, each page needs 11 entries (10 versions plus `x-default`). ```xml https://example.com/en/about https://example.com/es/acerca-de ``` Each `` entry lists every version, including itself. Submit the file in Google Search Console under `Sitemaps`. The [XML sitemap guide for developers](/articles/xml-sitemap-best-practices-developers) covers sitemap indexes for large files. ### HTTP headers for files that are not HTML Use headers for PDFs and other files that have no ``: ``` Link: ; rel="alternate"; hreflang="en", ; rel="alternate"; hreflang="es", ; rel="alternate"; hreflang="fr", ; rel="alternate"; hreflang="x-default" ``` In Nginx: ```nginx location ~* \.pdf$ { add_header Link '; rel="alternate"; hreflang="en"' always; add_header Link '; rel="alternate"; hreflang="es"' always; add_header Link '; rel="alternate"; hreflang="fr"' always; add_header Link '; rel="alternate"; hreflang="x-default"' always; } ``` This example sends the same set for every PDF. In production, map each file to its own alternates. Most sites need this method rarely. ## Avoid five common mistakes ### Mistake 1: no self-reference Each page must list itself. This English page lists only the other versions: ```html ``` Add the English entry: ```html ``` ### Mistake 2: no return link The English page lists English and Spanish. The Spanish page lists only Spanish. Google ignores the pair. Both pages must list the full set: ```html ``` ### Mistake 3: invented codes `hreflang="spanish"` is not valid, and `en-uk` is not valid. Use `es` and `en-gb`. ### Mistake 4: a canonical tag that points to another language This Spanish page has a canonical tag that points to the English page: ```html ``` The canonical tag says "this page is a copy of the English page." The hreflang tag says "this is the Spanish version." The signals conflict. Give each language version a self-referencing canonical: ```html ``` Also point every hreflang entry at the canonical, indexable URL. Do not point it at a redirect, a `noindex` page, or a URL with tracking parameters. The [canonical tag guide](/articles/canonical-tags-developers) covers the canonical side. ### Mistake 5: no x-default A site with `en-us`, `en-gb`, and `es-es` versions has no page for a searcher in Canada who reads French. Add `x-default`: ```html ``` ## Implement hreflang on common platforms ### WordPress WPML is a paid plugin that adds hreflang tags. Install it, add your languages under `Settings`, then `Languages`, and choose a language URL format such as `/en/` and `/es/`. WPML then adds the tags to each translated page. Polylang is free. Install it and add your languages under `Settings`, then `Languages`. For WooCommerce, add Polylang for WooCommerce. Polylang adds the tags to each translated page. ### Next.js The Pages Router has built-in locale routing: ```javascript module.exports = { i18n: { locales: ['en', 'es', 'fr'], defaultLocale: 'en', }, }; ``` This produces URLs such as `/es/about` and `/fr/about`. It does not translate slugs. If you want `/es/acerca-de`, you must map each slug to its translations yourself. Write the tags in a shared component. In JSX, the attribute is `hrefLang`: ```javascript import Head from 'next/head'; import { useRouter } from 'next/router'; export default function SEOHead() { const { locales, asPath } = useRouter(); return ( {locales.map((loc) => ( ))} ); } ``` The App Router does not use the `i18n` setting. Put the locale in the route, such as `app/[lang]/about/page.js`, and return the alternates from `generateMetadata` in `alternates.languages`. ### A headless CMS In Contentful, mark the fields that differ by language as localized: ```json { "name": "Page", "fields": [ { "id": "title", "name": "Title", "type": "Symbol", "localized": true }, { "id": "slug", "name": "Slug", "type": "Symbol", "localized": true }, { "id": "body", "name": "Body", "type": "RichText", "localized": true } ] } ``` Fetch each locale: ```javascript const entries = await client.getEntries({ content_type: 'page', 'fields.slug': slug, locale: 'en-US', // or 'es-ES', 'fr-FR' }); ``` Then build the tag list from the slug of each locale: ```javascript export function generateHreflangTags(slugsByLocale) { return Object.entries(slugsByLocale).map(([locale, slug]) => ({ hreflang: locale, href: `https://example.com/${locale.toLowerCase()}/${slug}`, })); } ``` The [headless CMS SEO guide](/articles/headless-cms-seo-developers) covers the other SEO fields such a model needs. ### Subdomains and separate domains Hreflang works across subdomains and across domains with the same syntax: ```html ``` ### Regional pricing on ecommerce pages Suppose `https://example.com/en-us/product` shows prices in US dollars and `https://example.com/en-gb/product` shows prices in pounds. The text is 90 percent the same. The regional difference still justifies two URLs and hreflang: ```html ``` ## Validate and maintain the tags Google retired the International Targeting report in Search Console in September 2022. It no longer lists hreflang errors. Use crawlers instead. To audit with Screaming Frog: 1. Turn on hreflang storage in the crawl configuration. 2. Crawl the site. 3. Open the `Hreflang` tab. 4. Filter for missing return links, missing self-reference, invalid codes, and links to non-canonical URLs. 5. Export the errors and fix them. To check a single page, use an online checker such as hreflang.org. It extracts the tags and tests the syntax and the return links. After you fix errors, allow two to four weeks for Google to recrawl the pages and apply the new signals. Hreflang is not a ranking signal. It controls which version Google shows to which searcher. Hreflang errors fail without a warning. Rankings in a target country fall, and no report tells you why. Audit the tags each quarter and after each release that touches templates or URLs. The [international SEO guide](/articles/international-seo-guide) covers the URL structure decisions that come before hreflang. ---- ```text .|########||. .|########||. .|########||. |##||. .||##|. |##||. .||##|. |##||. .||##|. |#|. .|#|. |#|. .|#|. |#|. .|#|. |#| |#| |#| |#| |#| |#| .#| |#. .#| |#. .#| |#. .#. .#| .#. .#| .#. .#| |#. .#| |#. .#| |#. .#| |# ...... #| |# ...... #| |# ...... #| .# ||#########| #| .# ||#########| #| .# ||#########| #| .#. |######||######|. .#. .#. |######||######|. .#. .#. |######||######|. .#. #. .##|###|##|#|######| .# #. .##|###|##|#|######| .# #. .##|###|##|#|######| .# || |##|#||||||||||||#||#| || || |##|#||||||||||||#||#| || || |##|#||||||||||||#||#| || # |#||||||||||||||||||||#| #. # |#||||||||||||||||||||#| #. # |#||||||||||||||||||||#| #. || |#||||||||||||||||||||||#| || || |#||||||||||||||||||||||#| || || |#||||||||||||||||||||||#| || # .#||||||||||||||||||||||||#| # # .#||||||||||||||||||||||||#| # # .#||||||||||||||||||||||||#| # || ....|||#||||||##|#|||#|#||##||||....|. || || ....|||#||||||##|#|||#|#||##||||....|. || || ....|||#||||||##|#|||#|#||##||||....|. || #. . ....|# ....#||| ||| .#||| ....#. .# #. . ....|# ....#||| ||| .#||| ....#. .# #. . ....|# ....#||| ||| .#||| ....#. .# # . ||||#| .#####|| . .#| .#||| ||||# #. # . ||||#| .#####|| . .#| .#||| ||||# #. # . ||||#| .#####|| . .#| .#||| ||||# #. .| ||||| #. |#|||||. || #. |#||. .||||| || .| ||||| #. |#|||||. || #. |#||. .||||| || .| ||||| #. |#|||||. || #. |#||. .||||| || || |.... #. ....|#. |. ...|. ....|| || || |.... #. ....|#. |. ...|. ....|| || || |.... #. ....|#. |. ...|. ....|| || #. .||||||##||||||##||####|||||||#||||||#| .# #. .||||||##||||||##||####|||||||#||||||#| .# #. .||||||##||||||##||####|||||||#||||||#| .# # .||####|###########################|. # # .||####|###########################|. # # .||####|###########################|. # # .#||||||.#.|| # |. ..# #| #|||||#| # # .#||||||.#.|| # |. ..# #| #|||||#| # # .#||||||.#.|| # |. ..# #| #|||||#| # # .#|||||| .. |# ## |#| ...#|#|||#| # # .#|||||| .. |# ## |#| ...#|#|||#| # # .#|||||| .. |# ## |#| ...#|#|||#| # # .#|||#|# .# .#| #| ##|.#..#|||||#| # # .#|||#|# .# .#| #| ##|.#..#|||||#| # # .#|||#|# .# .#| #| ##|.#..#|||||#| # # .#||||||############|######|||||#| # # .#||||||############|######|||||#| # # .#||||||############|######|||||#| # # |...||#||||||#||||#|#||||||#|||||#||| |.| # # |...||#||||||#||||#|#||||||#|||||#||| |.| # # |...||#||||||#||||#|#||||||#|||||#||| |.| # #. .. ||||# .|||##|. |#| .|| || .|||#. #| # .# #. .. ||||# .|||##|. |#| .|| || .|||#. #| # .# #. .. ||||# .|||##|. |#| .|| || .|||#. #| # .# || | ...|| ...##| | #| .|. |. ##### .. .| || || | ...|| ...##| | #| .|. |. ##### .. .| || || | ...|| ...##| | #| .|. |. ##### .. .| || || ||||| || ||||#| . |. |. |#. ||||| |#| || || || ||||| || ||||#| . |. |. |#. ||||| |#| || || || ||||| || ||||#| . |. |. |#. ||||| |#| || || .# |.....#|....|#.||||.|||##.|#|....||.#||.#. #. .# |.....#|....|#.||||.|||##.|#|....||.#||.#. #. .# |.....#|....|#.||||.|||##.|#|....||.#||.#. #. #.|||||||#############################| ||| .# #.|||||||#############################| ||| .# #.|||||||#############################| ||| .# || ##||#||#||||||#||#||#||#||##. || || ##||#||#||||||#||#||#||#||##. || || ##||#||#||||||#||#||#||#||##. || # .#|||||||||#||#|||||||||||#| # # .#|||||||||#||#|||||||||||#| # # .#|||||||||#||#|||||||||||#| # || |#||||||||||||||||||||||#| || || |#||||||||||||||||||||||#| || || |#||||||||||||||||||||||#| || .# |#||||||||||||||||||||#| #. .# |#||||||||||||||||||||#| #. .# |#||||||||||||||||||||#| #. || |#||||||||||||||||||#| || || |#||||||||||||||||||#| || || |#||||||||||||||||||#| || #. .######|#|#########| .# #. .######|#|#########| .# #. .######|#|#########| .# .#. |#####||||#####| .#. .#. |#####||||#####| .#. .#. |#####||||#####| .#. |# ||########|| #. |# ||########|| #. |# ||########|| #. |# ...... #| |# ...... #| |# ...... #| |#. .#| |#. .#| |#. .#| |#. .#. |#. .#. |#. .#. .#| |#. .#| |#. .#| |#. |#| |#| |#| |#| |#| |#| .|#|. .|#|. .|#|. .|#|. .|#|. .|#|. |##||. .||##| |##||. .||##| |##||. .||##| .||########||. .||########||. .||########||. Scale With Search 2026 [scalewithsearch.com](https://scalewithsearch.com) ```