The Hreflang Complete Guide 2026 (with Next.js Examples)

Your website can be technically perfect in English and still invisible to most of the world.

English covers just 49.7% of all web content (W3Techs, May 2026). That means the other half of the web operates in other languages — and without the right signal, Google has to guess which version of your page belongs to which audience. Your German visitors get an English page. They bounce. You lose the conversion.

Hreflang is the HTML attribute that fixes this. And it's broken on the majority of multilingual sites.

In this guide, we walk through what hreflang is, how to write it without the common errors that trip up most developers, and exactly how to implement it in a Next.js 15 App Router project — including the patterns we use when managing 10 language variants across multilingual builds.

Key Takeaways

• 58% of multilingual websites have internal hreflang conflicts in their source code (Semrush, 2023)
• 76% of online shoppers prefer to buy in their native language — 40% won't buy at all from a site in a different language (CSA Research, 2020)
• Google treats hreflang as a hint, not a directive — unreliable tags get ignored, but the duplicate content problem remains
• In Next.js 15 App Router, alternates.languages inside generateMetadata() is the correct zero-dependency implementation method
• 96% of sites with hreflang conflicts are missing the self-referencing tag — one simple omission breaks the entire cluster (Semrush, 2023)

What Is Hreflang and Why Does It Matter for Your Rankings?

Only 25.9% of internet users primarily browse online in English (Internet World Stats via Wikipedia, 2025). Yet Google's job is to serve each user content in their own language — and without hreflang, it has to guess from context signals alone. Hreflang is an HTML attribute that tells Google precisely which language and regional version of a page to show to which user.

The basic syntax looks like this:

``html ``

This block must appear on all language versions of the page — including the English version linking to itself. Miss that self-reference on a single page and the entire hreflang cluster for that URL becomes unreliable in Google's eyes.

Why does getting this right move commercial outcomes? A CSA Research survey of 8,709 consumers across 29 countries found that 76% prefer to buy products with information in their native language, and 65% would choose a native-language page even if the translation quality is lower than an English-language alternative (CSA Research "Can't Read, Won't Buy", 2020). Hreflang doesn't just help rankings — it determines whether translated traffic converts.

The 58% internal conflict rate is striking, but the root cause is almost always the same: developers add hreflang to the English page template and forget to mirror the full cluster on the translated pages. A missing self-reference on the German page invalidates the connection Google needs to confirm the English and German pages are genuine variants of each other — not duplicates.

How Does Google Actually Use Hreflang?

Here's what most hreflang guides miss: Google confirmed that hreflang tags are treated as hints, not directives. Google won't penalize broken hreflang — it'll silently ignore tags it deems unreliable. The danger is in what happens without the hint: Google treats your language variants as separate pages competing for the same keyword, often showing the wrong language to searchers or creating a self-competing duplicate content situation.

The reciprocal requirement is the core rule. Every language version of a page must include hreflang tags pointing to all other versions, including itself. If your English page links to the German page but the German page doesn't link back to the English page, the cluster is broken.

What Google validates on each hreflang tag: - The hreflang value matches the actual language of the linked page - The href is the absolute canonical URL — relative URLs fail silently - All pages in the cluster reference each other bidirectionally

A language mismatch — declaring hreflang="de" on a page that's actually in English — signals to Google that your entire hreflang setup may be unreliable. The Semrush study found 21% of multilingual sites have this problem (Semrush, 2023). This usually happens when a page hasn't been translated yet but still carries hreflang tags pointing to the English content.

How to Write Hreflang Attributes Correctly

The most error-prone part of hreflang isn't the attribute name — it's the language code value. A Semrush study found 15% of multilingual sites use invalid hreflang code formats, usually from confusing the separator character or mixing up language and country codes (Semrush, 2023).

The rules: - Use ISO 639-1 two-letter language codes: en, de, fr, sv - Optionally combine with ISO 3166-1 Alpha-2 country codes using a hyphen: en-GB, de-CH, pt-BR - Never use underscores — en_US is wrong; en-US is correct - Always include x-default for the fallback page

| Intended Language | Correct hreflang | Common wrong value | |---|---|---| | English (global) | en | en-EN, english | | English (UK) | en-GB | en_GB, eng-UK | | German (Germany) | de | ger, de_DE with underscore | | German (Switzerland) | de-CH | ch, de_CH with underscore | | Swedish | sv | sw, swe | | Norwegian Bokmål | nb | no | | Portuguese (Brazil) | pt-BR | pt_BR with underscore | | Fallback / selector | x-default | default, x_default |

The Swedish and Norwegian entries are the most misunderstood. Swedish's ISO 639-1 code is sv, not sw. Norwegian has two written standards: nb (Bokmål) and nn (Nynorsk). Most Norwegian sites should use nb. Using no in hreflang is technically incorrect — it doesn't map to a valid IANA language subtag.

Swiss German deserves its own note: ch is Switzerland's country code, not a language code. The hreflang value for Swiss German content is de-CH. Using ch alone as an hreflang value is invalid and will be ignored.

How to Implement Hreflang in Next.js 15 App Router

Next.js 15's App Router makes hreflang implementation clean and framework-native — no third-party SEO packages needed. We manage 10 language variants across our multilingual builds (English, Finnish, French, German, Italian, Norwegian, Swiss German, Serbian, Spanish, and Swedish) and the pattern below is what we run in production.

The key is the alternates.languages field inside generateMetadata(). Next.js renders it as tags in automatically, with no custom rendering needed.

Step 1: Build an explicit language code mapping

Your internal URL language keys don't always match ISO hreflang codes. Build an explicit map to avoid runtime bugs:

``typescript // src/lib/hreflang.ts export const HREFLANG_CODE: Record = { en: 'en', fi: 'fi', fr: 'fr', de: 'de', it: 'it', no: 'nb', // Norwegian Bokmål — ISO hreflang code is nb, not no ch: 'de-CH', // Swiss German — URL prefix /ch, hreflang value de-CH sr: 'sr', es: 'es', sw: 'sv', // Swedish — internal key sw, ISO hreflang code sv }; ``

Two real production gotchas: Norwegian's hreflang value is nb, not no. And Swedish's ISO code is sv — using sw (which is internally convenient as a DB table prefix) in the hreflang attribute is invalid. This explicit map is what prevents those bugs from reaching production.

Step 2: Build a centralized getAlternates helper

```typescript // src/lib/hreflang.ts (continued) const BASE_URL = 'https://fridamarketing.com'; const LANG_CODES = ['fi', 'fr', 'de', 'it', 'no', 'ch', 'sr', 'es', 'sw']; // URL prefix for each lang key (ch → no prefix needed? no → /no) const LANG_URL: Record = { fi: 'fi', fr: 'fr', de: 'de', it: 'it', no: 'no', ch: 'ch', sr: 'sr', es: 'es', sw: 'sv', };

export function getAlternates(routeKey: string, currentLang?: string) { const languages: Record = { en: ${BASE_URL}/${routeKey}, };

for (const lang of LANG_CODES) { const urlPrefix = LANG_URL[lang]; const hreflangCode = HREFLANG_CODE[lang]; languages[hreflangCode] = ${BASE_URL}/${urlPrefix}/${routeKey}; }

const canonical = currentLang ? ${BASE_URL}/${LANG_URL[currentLang] || currentLang}/${routeKey} : ${BASE_URL}/${routeKey};

return { canonical, languages: { ...languages, 'x-default': ${BASE_URL}/${routeKey} }, }; } ```

Step 3: Use it inside generateMetadata()

For the English page:

```typescript // app/about/page.tsx import { getAlternates } from '@/lib/hreflang';

export async function generateMetadata() { return { title: 'About Us | Frida Marketing', description: 'Next.js development and multilingual SEO agency.', alternates: getAlternates('about'), }; } ```

For language variants:

```typescript // app/[lang]/about/page.tsx import { getAlternates } from '@/lib/hreflang';

export async function generateMetadata({ params }: { params: { lang: string } }) { return { title: 'About Us | Frida Marketing', description: 'Next.js development and multilingual SEO agency.', alternates: getAlternates('about', params.lang), }; } ```

Next.js compiles the alternates.languages object into the full set of tags automatically. Every language, including the self-reference for the current page, gets rendered correctly as long as the mapping is complete.

According to a DeepL and Regina Corso Consulting survey of senior marketers across the US, Germany, Japan, and France, 96% reported positive ROI from translation and localization efforts, and 65% reported a return of 3x or greater (BusinessWire, 2024). The technical overhead of correct hreflang is modest compared to the revenue locked behind it.

Which Hreflang Method Should You Use?

There are three ways to declare hreflang: HTML tags, XML sitemap entries, or HTTP response headers. All three are valid to Google — the right choice depends on your stack and content volume.

| Method | How it works | Best for | |---|---|---| | HTML tags | injected in each page's | Next.js App Router via generateMetadata() | | XML sitemap | inside each block in sitemap.xml | CMS-managed sites, large page volumes | | HTTP headers | Link: header in the server response | Non-HTML content (PDFs, JSON endpoints) |

For Next.js, the generateMetadata() approach is the right default. It keeps hreflang declarations co-located with the page logic, is type-checked at build time, and requires no separate sitemap maintenance. The sitemap approach is a useful supplement on large sites but shouldn't be the only source of hreflang when the framework handles it natively.

One thing worth noting: you can declare hreflang in both the tags and the sitemap on the same site. Google accepts both and they don't conflict. But maintaining two sources of truth for the same data is something to avoid — keep it in generateMetadata() and let the sitemap handle crawl priority separately.

How to Test and Validate Your Hreflang Setup

Deploying hreflang is half the job. Validating that Google picked it up correctly is the other half. These four tools cover different failure modes — use at least two.

Google Search Console — International Targeting report After deploying, open GSC → Legacy tools → International Targeting. It shows which language variants Google has indexed and flags any hreflang configuration errors it detected. This is your ground truth — if GSC shows a language or region flag raised, investigate before anything else.

Semrush Site Audit Run a full audit and filter for hreflang issues. Semrush catches missing self-references, broken hreflang URLs, and language mismatches — the three most common failure modes across 20,000 tested sites.

Ahrefs Site Audit Ahrefs reports on which pages are missing from a complete hreflang cluster, which is valuable when you have 10 languages and need to confirm every variant cross-references all others. It finds gaps that Semrush sometimes misses.

hreflang.org — free single-URL checker Paste a URL, get all its hreflang tags displayed, and verify the cluster is reciprocal. Fast for one-off spot checks during development before a full site audit.

One thing auditing tools won't catch: hreflang that is technically valid but semantically wrong. If you declare hreflang="de-CH" on a page that serves generic German content rather than Swiss German content, the tags pass every validator. But Google eventually infers from behavioral signals that Swiss users aren't being well served, and trust in your hreflang cluster decreases over time. Technical validation is just the baseline — matching content to the declared locale is the real goal.

---

We build multilingual Next.js sites with complete hreflang implementation from day one — correct language code mapping, translated sitemaps, language-specific schema markup, and structured hreflang audits after launch. Get in touch to discuss your project, or see our pricing for multilingual development and SEO packages.

---

Frequently Asked Questions

What is hreflang and what does it do?

Hreflang is an HTML link attribute that tells Google which language version of a page to serve to users in specific regions or languages. Correct implementation prevents Google showing the wrong language version, reduces bounce rate, and avoids duplicate content penalties across language variants.

Does hreflang directly improve Google rankings?

Google treats hreflang as a hint, not a directive — it ignores tags it finds unreliable. Correct implementation prevents the wrong language being shown to searchers, reducing bounce rate and improving engagement signals that indirectly lift rankings. Broken hreflang creates duplicate content competition between your own language variants.

What are the most common hreflang mistakes?

A Semrush study of 20,000 multilingual websites found that 58% have internal source code conflicts, 37% link to broken or redirected URLs, 21% have a language mismatch between the declared hreflang value and the actual page language, and 15% use invalid language or country codes (Semrush, 2023).

How do I implement hreflang in Next.js 15 App Router?

In Next.js 15, export an alternates.languages object from generateMetadata(). Use ISO 639-1 language codes as keys and absolute canonical URLs as values. Include x-default pointing to your default locale. Next.js automatically renders these as tags in the document head — no separate rendering or third-party library needed.

What is x-default hreflang used for?

x-default designates a fallback page for users whose language or region doesn't match any of your declared hreflang values. It's typically the English version or a language-selector landing page. Always include it — it signals to Google that you've intentionally accounted for visitors from unlisted locales rather than just missing the tag.

Conclusion

Hreflang is one of those technical SEO elements that's easy to get partially right and hard to get fully right. The syntax is simple, but the failure modes — missing self-references, relative URLs, incorrect ISO codes, unrecipricated links between language variants — are subtle and don't surface as visible errors until you're looking at the wrong language ranking in the wrong market.

In Next.js 15, the alternates.languages API in generateMetadata() handles the rendering cleanly and without extra packages. The real investment is in the mapping layer: making sure every internal language key resolves to a valid ISO hreflang code, and that the canonical URLs you pass are absolute and point to the page actually being indexed.

If you're building a multilingual Next.js site and want a review of your hreflang setup, reach out — we'll identify exactly which clusters have issues before Google flags them.