Hreflang Tags in Nuxt · Nuxt SEO
[NuxtSEO](https://nuxtseo.com/ "Home")
- [Modules](https://nuxtseo.com/docs/nuxt-seo/getting-started/introduction)
- [Tools](https://nuxtseo.com/tools)
- [Pro](https://nuxtseo.com/pro)
- [Learn SEO](https://nuxtseo.com/learn-seo/nuxt) [Releases](https://nuxtseo.com/releases)
[1.4K](https://github.com/harlan-zw/nuxt-seo)
[Nuxt SEO on GitHub](https://github.com/harlan-zw/nuxt-seo)
Learn SEO
Master search optimization
Nuxt
Vue
[SEO Checklist](https://nuxtseo.com/learn-seo/checklist) [Pre-Launch Warmup](https://nuxtseo.com/learn-seo/pre-launch-warmup) [Backlinks & Authority](https://nuxtseo.com/learn-seo/backlinks)
[Mastering Meta](https://nuxtseo.com/learn-seo/nuxt/mastering-meta)
- [Titles](https://nuxtseo.com/learn-seo/nuxt/mastering-meta/titles)
- [Meta Description](https://nuxtseo.com/learn-seo/nuxt/mastering-meta/descriptions)
- [Image Alt Text](https://nuxtseo.com/learn-seo/nuxt/mastering-meta/alt-text)
- [Social Sharing](https://nuxtseo.com/learn-seo/nuxt/mastering-meta/open-graph)
- [Rich Results](https://nuxtseo.com/learn-seo/nuxt/mastering-meta/rich-results)
- [Schema.org](https://nuxtseo.com/learn-seo/nuxt/mastering-meta/schema-org)
- [Twitter Cards](https://nuxtseo.com/learn-seo/nuxt/mastering-meta/twitter-cards)
[ Controlling Crawlers](https://nuxtseo.com/learn-seo/nuxt/controlling-crawlers)
- [Robots Txt](https://nuxtseo.com/learn-seo/nuxt/controlling-crawlers/robots-txt)
- [Sitemaps](https://nuxtseo.com/learn-seo/nuxt/controlling-crawlers/sitemaps)
- [Robot Meta Tag](https://nuxtseo.com/learn-seo/nuxt/controlling-crawlers/meta-tags)
- [Canonical Link Tag](https://nuxtseo.com/learn-seo/nuxt/controlling-crawlers/canonical-urls)
- [HTTP Redirects](https://nuxtseo.com/learn-seo/nuxt/controlling-crawlers/redirects)
- [Duplicate Content](https://nuxtseo.com/learn-seo/nuxt/controlling-crawlers/duplicate-content)
- [llms.txt](https://nuxtseo.com/learn-seo/nuxt/controlling-crawlers/llms-txt)
[ Routes & Rendering](https://nuxtseo.com/learn-seo/nuxt/routes-and-rendering)
- [URL Structure](https://nuxtseo.com/learn-seo/nuxt/routes-and-rendering/url-structure)
- [Pagination](https://nuxtseo.com/learn-seo/nuxt/routes-and-rendering/pagination)
- [Trailing Slashes](https://nuxtseo.com/learn-seo/nuxt/routes-and-rendering/trailing-slashes)
- [Query Parameters](https://nuxtseo.com/learn-seo/nuxt/routes-and-rendering/query-parameters)
- [Hreflang & i18n](https://nuxtseo.com/learn-seo/nuxt/routes-and-rendering/i18n)
- [404 Pages](https://nuxtseo.com/learn-seo/nuxt/routes-and-rendering/404-pages)
- [Dynamic Routes](https://nuxtseo.com/learn-seo/nuxt/routes-and-rendering/dynamic-routes)
- [Internal Linking](https://nuxtseo.com/learn-seo/nuxt/routes-and-rendering/internal-linking)
- [Programmatic SEO](https://nuxtseo.com/learn-seo/nuxt/routes-and-rendering/programmatic-seo)
- [Rendering Modes](https://nuxtseo.com/learn-seo/nuxt/routes-and-rendering/rendering)
- [Security](https://nuxtseo.com/learn-seo/nuxt/routes-and-rendering/security)
[ Launch & Listen](https://nuxtseo.com/learn-seo/nuxt/launch-and-listen)
- [Getting Indexed](https://nuxtseo.com/learn-seo/nuxt/launch-and-listen/going-live)
- [Google Search Console](https://nuxtseo.com/learn-seo/nuxt/launch-and-listen/search-console)
- [Core Web Vitals](https://nuxtseo.com/learn-seo/nuxt/launch-and-listen/core-web-vitals)
- [Indexing Issues](https://nuxtseo.com/learn-seo/nuxt/launch-and-listen/indexing-issues)
- [SEO Monitoring](https://nuxtseo.com/learn-seo/nuxt/launch-and-listen/seo-monitoring)
- [Site Migration](https://nuxtseo.com/learn-seo/nuxt/launch-and-listen/site-migration)
- [IndexNow](https://nuxtseo.com/learn-seo/nuxt/launch-and-listen/indexnow)
- [Debugging](https://nuxtseo.com/learn-seo/nuxt/launch-and-listen/debugging)
- [AI Search Optimization](https://nuxtseo.com/learn-seo/nuxt/launch-and-listen/ai-optimized-content)
1. [Learn SEO for Nuxt](https://nuxtseo.com/learn-seo)
2.
3. [Routes And Rendering](https://nuxtseo.com/learn-seo/nuxt/routes-and-rendering)
4.
5. [I18n](https://nuxtseo.com/learn-seo/nuxt/routes-and-rendering/i18n)
# Hreflang Tags in Nuxt
Set hreflang tags in Nuxt to tell search engines which language version to show users. Avoid duplicate content penalties across multilingual sites.
[Harlan Wilton](https://x.com/harlan-zw)12 mins read Published Dec 17, 2025
Hreflang tags tell search engines which language version of your page to show users. Without them, Google might show your French content to English speakers or rank the wrong regional version, creating [duplicate content](https://nuxtseo.com/learn-seo/nuxt/controlling-crawlers/duplicate-content) issues across languages.
```
```
[Google recommends hreflang](https://developers.google.com/search/docs/specialty/international/localized-versions) when you have:
- Same content in different languages
- Regional variations (en-US vs en-GB)
- Partial translations mixed with original language
Hreflang is a signal, not a directive. Search engines can ignore it if they think a different version better matches user intent.
## [Quick Reference](#quick-reference)
useHead
```
useHead({
link: [
{ rel: 'alternate', hreflang: 'en', href: 'https://example.com/en' },
{ rel: 'alternate', hreflang: 'fr', href: 'https://example.com/fr' },
{ rel: 'alternate', hreflang: 'x-default', href: 'https://example.com/en' }
]
})
```
## [Hreflang Format](#hreflang-format)
Hreflang values use [ISO 639-1 language codes](https://www.linguise.com/blog/guide/list-of-the-hreflang-language-codes-how-to-implement-them/) and optional [ISO 3166-1 Alpha-2 region codes](https://hreflang.org/what-is-a-valid-hreflang/):
| Format | Example | Use Case |
| --- | --- | --- |
| Language only | `en` | English content for all regions |
| Language + region | `en-US` | English for United States |
| Language + region | `en-GB` | English for United Kingdom |
| Special fallback | `x-default` | Default for unmatched languages/regions |
Language codes must be lowercase. Region codes must be uppercase. Separate with hyphen: `en-US`.
### [Common Examples](#common-examples)
```
en English (all regions)
fr French (all regions)
es Spanish (all regions)
en-US English for USA
en-GB English for UK
fr-CA French for Canada
es-MX Spanish for Mexico
zh-CN Simplified Chinese (China)
zh-TW Traditional Chinese (Taiwan)
```
### [Region Codes Are Tricky](#region-codes-are-tricky)
[UK is Ukraine](https://www.weglot.com/blog/hreflang-language-codes), not United Kingdom. Use `GB` for Great Britain. [Chinese uses zh-CN/zh-TW or zh-Hans/zh-Hant](https://www.seroundtable.com/google-iso-3166-1-for-hreflang-24663.html) for simplified/traditional variants since ISO 639-1 only defines one `zh` code.
## [Manual Implementation](#manual-implementation)
If you're not using @nuxtjs/i18n, set hreflang manually with `useHead()`:
```
```
### [Creating a Composable](#creating-a-composable)
Extract hreflang logic into `composables/useHreflang.ts`:
```
// composables/useHreflang.ts - auto-imported in Nuxt
export function useHreflang(locales: string[]) {
const route = useRoute()
const links = computed(() => {
const baseUrl = 'https://example.com'
return [
...locales.map(locale => ({
rel: 'alternate',
hreflang: locale,
href: \`${baseUrl}/${locale}${route.path}\`
})),
{
rel: 'alternate',
hreflang: 'x-default',
href: \`${baseUrl}/${locales[0]}${route.path}\`
}
]
})
useHead({ link: links })
}
```
Use it in pages:
```
```
## [Automatic Implementation with @nuxtjs/i18n](#automatic-implementation-with-nuxtjsi18n)
The [@nuxtjs/i18n](https://i18n.nuxtjs.org/) module automatically generates hreflang tags for all configured locales. Nuxt handles return links, self-referential tags, and x-default automatically.
```
// nuxt.config.ts
export default defineNuxtConfig({
modules: ['@nuxtjs/i18n'],
i18n: {
locales: [
{ code: 'en', iso: 'en-US', file: 'en.json' },
{ code: 'fr', iso: 'fr-FR', file: 'fr.json' },
{ code: 'de', iso: 'de-DE', file: 'de.json' }
],
defaultLocale: 'en',
strategy: 'prefix', // URLs like /en, /fr, /de
// SEO features
baseUrl: 'https://example.com',
detectBrowserLanguage: {
useCookie: true,
cookieKey: 'i18n_redirected',
redirectOn: 'root'
}
}
})
```
Nuxt automatically generates:
```
```
### [URL Strategies](#url-strategies)
The i18n module supports different URL patterns:
| Strategy | Example | Notes |
| --- | --- | --- |
| `prefix` | `/en/about`, `/fr/about` | Default locale also gets prefix |
| `prefix_except_default` | `/about`, `/fr/about` | Default locale has no prefix |
| `prefix_and_default` | `/about`, `/en/about`, `/fr/about` | Both work for default |
| `no_prefix` | `/about` | Locale in cookie/domain only |
```
// nuxt.config.ts
export default defineNuxtConfig({
i18n: {
strategy: 'prefix_except_default', // /about (en), /fr/about
defaultLocale: 'en'
}
})
```
### [Domain-Based Locales](#domain-based-locales)
For sites with different domains per language:
```
// nuxt.config.ts
export default defineNuxtConfig({
i18n: {
locales: [
{ code: 'en', iso: 'en-US', domain: 'example.com' },
{ code: 'fr', iso: 'fr-FR', domain: 'example.fr' },
{ code: 'de', iso: 'de-DE', domain: 'example.de' }
],
strategy: 'no_prefix',
differentDomains: true
}
})
```
Generates:
```
```
## [X-Default Tag](#x-default-tag)
The `x-default` hreflang provides a fallback URL when no language matches the user's preferences. [Google recommends x-default](https://www.weglot.com/guides/hreflang-tag) for all hreflang clusters.
```
```
### [When to Use X-Default](#when-to-use-x-default)
Set x-default to:
- Your primary language version
- A language selector page
- The most universally understood language version
```
// Point x-default to language selector
useHead({
link: [
{ rel: 'alternate', hreflang: 'en-US', href: 'https://example.com/en-us' },
{ rel: 'alternate', hreflang: 'en-GB', href: 'https://example.com/en-gb' },
{ rel: 'alternate', hreflang: 'fr-FR', href: 'https://example.com/fr-fr' },
{ rel: 'alternate', hreflang: 'x-default', href: 'https://example.com/choose-language' }
]
})
```
[According to Victorious](https://developers.google.com/search/docs/specialty/international/localized-versions#x-default), x-default improves user experience by routing unmatched users to an appropriate fallback instead of a random language version.
## [Hreflang Rules](#hreflang-rules)
### [1. Bidirectional Links (Return Links)](#_1-bidirectional-links-return-links)
Every page referenced in hreflang must link back. If page A links to page B, page B must link to page A. [This is the most common hreflang error](https://developers.google.com/search/docs/specialty/international/localized-versions).
```
```
### [2. Self-Referential Links](#_2-self-referential-links)
Each page must include a hreflang tag pointing to itself:
```
```
### [3. Use Canonical URLs Only](#_3-use-canonical-urls-only)
All hreflang URLs must:
- Return HTTP 200 status
- Be indexable (no `noindex`)
- Not be blocked by robots.txt
- Point to canonical URLs (not redirects)
[According to I Love SEO](https://developers.google.com/search/docs/specialty/international/localized-versions), using non-200, non-indexable, or non-canonical URLs is the root cause of most hreflang mistakes.
```
```
### [4. Canonical vs Hreflang](#_4-canonical-vs-hreflang)
Canonical tags and hreflang serve different purposes. Don't use canonical to point between language versions. [that signals duplicate content](https://developers.google.com/search/docs/specialty/international/localized-versions), not translations.
```
```
```
```
## [Implementation Methods](#implementation-methods)
You can implement hreflang using HTML `` tags, HTTP headers, or XML sitemaps. [Best practice is to choose one method](https://backlinko.com/hreflang-tag) and stick to it. Mixing methods creates conflicting signals.
### [HTML Link Tags (Recommended)](#html-link-tags-recommended)
Most flexible approach. Set per-page using `useHead()`:
```
```
### [HTTP Headers](#http-headers)
Useful for non-HTML resources (PDFs, etc.). Configure in server routes:
```
// server/routes/document.pdf.get.ts
export default defineEventHandler((event) => {
setHeader(event, 'Link', [
'; rel="alternate"; hreflang="en"',
'; rel="alternate"; hreflang="fr"',
'; rel="alternate"; hreflang="x-default"'
].join(', '))
return sendStream(event, createReadStream('/path/to/document.pdf'))
})
```
### [XML Sitemap](#xml-sitemap)
The [@nuxtjs/sitemap](https://nuxtseo.com/sitemap) module automatically generates hreflang annotations in sitemaps when used with @nuxtjs/i18n:
```
// nuxt.config.ts
export default defineNuxtConfig({
modules: ['@nuxtjs/sitemap', '@nuxtjs/i18n'],
sitemap: {
// Sitemap automatically includes hreflang from i18n config
}
})
```
Generates:
```
https://example.com/enhttps://example.com/fr
```
## [Common Mistakes](#common-mistakes)
### [Missing Return Links](#missing-return-links)
```
```
### [Non-Canonical URLs](#non-canonical-urls)
```
```
### [Noindex Pages](#noindex-pages)
```
```
All pages in hreflang cluster must be indexable. Remove `noindex` or remove the page from hreflang annotations.
### [Blocked by Robots.txt](#blocked-by-robotstxt)
If a URL is blocked in `robots.txt`, crawlers can't access it to validate hreflang links. Ensure all alternate URLs are crawlable.
### [Mixing with Canonical](#mixing-with-canonical)
```
```
## [Testing Hreflang](#testing-hreflang)
### [Manual Inspection](#manual-inspection)
View page source and verify:
- All alternate links are present
- Self-referential link exists
- x-default is set
- All URLs return 200
- All URLs are canonical (not redirects)
### [Google Search Console](#google-search-console)
After implementing hreflang, check [Google Search Console](https://search.google.com/search-console) > International Targeting for errors:
- Missing return tags
- Incorrect language codes
- Invalid URLs
### [Third-Party Tools](#third-party-tools)
- [Hreflang Tags Testing Tool](https://hreflang.org)
- [Merkle Hreflang Checker](https://technicalseo.com/tools/hreflang/)
- Search Console reports
## [Full Example: Multilingual Nuxt App](#full-example-multilingual-nuxt-app)
Complete implementation with @nuxtjs/i18n:
```
// nuxt.config.ts
export default defineNuxtConfig({
modules: ['@nuxtjs/i18n'],
i18n: {
locales: [
{ code: 'en', iso: 'en-US', file: 'en.json' },
{ code: 'fr', iso: 'fr-FR', file: 'fr.json' },
{ code: 'de', iso: 'de-DE', file: 'de.json' },
{ code: 'es', iso: 'es-ES', file: 'es.json' }
],
defaultLocale: 'en',
strategy: 'prefix',
langDir: 'locales',
baseUrl: 'https://example.com',
detectBrowserLanguage: {
useCookie: true,
cookieKey: 'i18n_redirected',
redirectOn: 'root'
}
}
})
```
```
// locales/en.json
{
"home": {
"title": "Welcome",
"description": "Welcome to our site"
}
}
```
```
// locales/fr.json
{
"home": {
"title": "Bienvenue",
"description": "Bienvenue sur notre site"
}
}
```
```