How to Fix Hreflang in Next.js / Nuxt
Next.js and Nuxt both ship with internationalisation features that include hreflang generation — but configuration is non-trivial and easy to get wrong. This guide covers framework-specific hreflang. Pair with hreflang guide and the Shopify version.
Step-by-step: How to configure hreflang in Next.js / Nuxt
- Choose URL pattern. Subpath (recommended): example.com/en/page, example.com/fr/page. Subdomain: en.example.com, fr.example.com. Domain: example.com, example.fr. Subpath is simplest in Next.js/Nuxt and works for most use cases.
- Configure Next.js App Router i18n. Manual approach with middleware.ts handling locale detection and routing. Or @next-intl or next-i18next libraries. App Router doesn't have built-in i18n config like Pages Router did — implementation is library-driven.
- Configure Pages Router i18n. next.config.js with i18n key: { locales: ['en', 'fr', 'de'], defaultLocale: 'en' }. Next.js handles locale routing automatically. Output hreflang via metadata API or next-seo.
- Configure Nuxt @nuxtjs/i18n. Add module, configure locales array with iso codes, route generation. @nuxtjs/i18n automatically generates hreflang link tags.
- Verify hreflang output. View source on a multilingual page → check for <link rel='alternate' hreflang='X' href='Y' /> tags. Should include all active locales plus x-default. Self-referencing tag also required.
- Generate locale-aware sitemap. next-sitemap with i18n config outputs per-locale URLs with hreflang alternates. Or @nuxtjs/sitemap with i18n integration. Submit one sitemap to Search Console; it covers all locales.
- Validate. hreflang.xyz, Aleyda Solis's validator, or Search Console International Targeting report. Common errors: missing return tags, mismatched language codes, x-default missing.
🌐 Validate Next.js hreflang
Find missing return tags, wrong codes and i18n issues.
Run Hreflang Validator →Frequently Asked Questions
Does Next.js App Router have built-in i18n like Pages Router?
No — App Router removed the i18n key from next.config.js. Implementation now uses middleware (Next.js docs recommend) or libraries (next-intl, next-i18next). More flexible, more code. Pages Router still supports built-in i18n if you're using it.
Best Next.js i18n library?
next-intl — modern, App Router-native, good DX. next-i18next — mature, more features, originally Pages Router-focused. For App Router new projects: next-intl. For Pages Router or migration: next-i18next.
How do I handle the default locale in Next.js i18n?
Two approaches: 1) Default locale has no prefix (example.com/page) — cleaner URLs but adds complexity to routing. 2) Default locale has prefix (example.com/en/page) — consistent, simpler. Next.js i18n config supports both via 'localeDetection' option. Most projects choose option 2 for simplicity.
Does Vercel deploy multi-locale Next.js sites correctly?
Yes — Vercel detects Next.js i18n config and routes all locales correctly. No special deployment configuration needed. Locale-based redirects also handled.
Why does Search Console show hreflang errors on my Next.js site?
Common: 'no return tags' (locale A points to B but B doesn't point back to A — usually a configuration gap). 'mismatched language codes' (using 'en' some places, 'en-US' others — be consistent). 'self-referencing missing' (each locale must hreflang to itself). Use a library to generate hreflang from i18n config; manual is error-prone.