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 Wilton12 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.

<head>
  <link rel="alternate" hreflang="en" href="https://example.com/en" />
  <link rel="alternate" hreflang="fr" href="https://example.com/fr" />
  <link rel="alternate" hreflang="x-default" href="https://example.com/en" />
</head>

Google recommends hreflang 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

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' }
  ]
})

useSeoMeta({
  alternateLanguages: {
    'en': 'https://example.com/en',
    'fr': 'https://example.com/fr',
    'x-default': 'https://example.com/en'
  }
})

Hreflang Format

Hreflang values use ISO 639-1 language codes and optional ISO 3166-1 Alpha-2 region codes:

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

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

UK is Ukraine, not United Kingdom. Use GB for Great Britain. Chinese uses zh-CN/zh-TW or zh-Hans/zh-Hant for simplified/traditional variants since ISO 639-1 only defines one zh code.

Automatic Implementation with @nuxtjs/i18n

The @nuxtjs/i18n 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:

<!-- On /en/about -->
<link rel="alternate" hreflang="en-US" href="https://example.com/en/about" />
<link rel="alternate" hreflang="fr-FR" href="https://example.com/fr/about" />
<link rel="alternate" hreflang="de-DE" href="https://example.com/de/about" />
<link rel="alternate" hreflang="x-default" href="https://example.com/en/about" />

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

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:

<link rel="alternate" hreflang="en-US" href="https://example.com/about" />
<link rel="alternate" hreflang="fr-FR" href="https://example.fr/about" />
<link rel="alternate" hreflang="de-DE" href="https://example.de/about" />

Manual Implementation

If you're not using @nuxtjs/i18n, set hreflang manually with useHead():

<script setup lang="ts">
const route = useRoute()

// Build alternate URLs based on current route
const alternates = [
  { lang: 'en', url: `https://example.com/en${route.path}` },
  { lang: 'fr', url: `https://example.com/fr${route.path}` },
  { lang: 'de', url: `https://example.com/de${route.path}` }
]

useHead({
  link: [
    ...alternates.map(alt => ({
      rel: 'alternate',
      hreflang: alt.lang,
      href: alt.url
    })),
    { rel: 'alternate', hreflang: 'x-default', href: 'https://example.com/en' }
  ]
})
</script>

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:

<script setup lang="ts">
useHreflang(['en', 'fr', 'de', 'es'])
</script>

X-Default Tag

The x-default hreflang provides a fallback URL when no language matches the user's preferences. Google recommends x-default for all hreflang clusters.

<!-- User with no matching language sees this -->
<link rel="alternate" hreflang="x-default" href="https://example.com/en" />

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, x-default improves user experience by routing unmatched users to an appropriate fallback instead of a random language version.

Hreflang Rules

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.

<!-- en page must reference fr page -->
<link rel="alternate" hreflang="fr" href="https://example.com/fr" />

<!-- fr page must reference en page -->
<link rel="alternate" hreflang="en" href="https://example.com/en" />

2. Self-Referential Links

Each page must include a hreflang tag pointing to itself:

<!-- On the English page -->
<link rel="alternate" hreflang="en" href="https://example.com/en" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr" />

<!-- On the French page -->
<link rel="alternate" hreflang="en" href="https://example.com/en" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr" />

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, using non-200, non-indexable, or non-canonical URLs is the root cause of most hreflang mistakes.

<script setup lang="ts">
// ✅ Good - points to canonical URL
useHead({
  link: [
    { rel: 'canonical', href: 'https://example.com/en/products' },
    { rel: 'alternate', hreflang: 'en', href: 'https://example.com/en/products' },
    { rel: 'alternate', hreflang: 'fr', href: 'https://example.com/fr/produits' }
  ]
})

// ❌ Bad - points to redirect
useHead({
  link: [
    { rel: 'alternate', hreflang: 'en', href: 'https://example.com/old-url' } // redirects to /en/products
  ]
})
</script>

4. Canonical vs Hreflang

Canonical tags and hreflang serve different purposes. Don't use canonical to point between language versions—that signals duplicate content, not translations.

<!-- ✅ Correct: each language version is canonical to itself -->
<!-- English page -->
<link rel="canonical" href="https://example.com/en/about" />
<link rel="alternate" hreflang="en" href="https://example.com/en/about" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr/a-propos" />

<!-- French page -->
<link rel="canonical" href="https://example.com/fr/a-propos" />
<link rel="alternate" hreflang="en" href="https://example.com/en/about" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr/a-propos" />

<!-- ❌ Wrong: canonical pointing between languages -->
<!-- French page -->
<link rel="canonical" href="https://example.com/en/about" />
<!-- This tells Google the French page is duplicate content -->

Implementation Methods

You can implement hreflang using HTML <link> tags, HTTP headers, or XML sitemaps. Best practice is to choose one method and stick to it. Mixing methods creates conflicting signals.

HTML Link Tags (Recommended)

Most flexible approach. Set per-page using useHead():

<script setup lang="ts">
useHead({
  link: [
    { rel: 'alternate', hreflang: 'en-US', href: 'https://example.com/us' },
    { rel: 'alternate', hreflang: 'en-GB', href: 'https://example.com/uk' },
    { rel: 'alternate', hreflang: 'x-default', href: 'https://example.com/us' }
  ]
})
</script>

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', [
    '<https://example.com/en/document.pdf>; rel="alternate"; hreflang="en"',
    '<https://example.com/fr/document.pdf>; rel="alternate"; hreflang="fr"',
    '<https://example.com/en/document.pdf>; rel="alternate"; hreflang="x-default"'
  ].join(', '))

  return sendStream(event, createReadStream('/path/to/document.pdf'))
})

XML Sitemap

The @nuxtjs/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:

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:xhtml="http://www.w3.org/1999/xhtml">
  <url>
    <loc>https://example.com/en</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/en" />
    <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr" />
    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/en" />
  </url>
  <url>
    <loc>https://example.com/fr</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/en" />
    <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr" />
    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/en" />
  </url>
</urlset>

Common Mistakes

Missing Return Links

<!-- ❌ English page links to French, but French doesn't link back -->
<!-- en page -->
<link rel="alternate" hreflang="fr" href="https://example.com/fr" />

<!-- fr page -->
<!-- Missing hreflang links! -->

Non-Canonical URLs

<!-- ❌ Linking to URL that redirects -->
<link rel="alternate" hreflang="en" href="https://example.com/en-us" />
<!-- But /en-us redirects to /us -->

<!-- ✅ Use final destination -->
<link rel="alternate" hreflang="en" href="https://example.com/us" />

Noindex Pages

<!-- ❌ Hreflang on noindex page -->
<meta name="robots" content="noindex" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr" />

All pages in hreflang cluster must be indexable. Remove noindex or remove the page from hreflang annotations.

Blocked by Robots.txt

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

<!-- ❌ Don't point canonical between languages -->
<!-- French page -->
<link rel="canonical" href="https://example.com/en" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr" />
<!-- Conflicting signals: canonical says "I'm a duplicate of EN"
     but hreflang says "I'm the French version" -->

Testing Hreflang

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

After implementing hreflang, check Google Search Console > International Targeting for errors:

Missing return tags
Incorrect language codes
Invalid URLs

Third-Party Tools

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"
  }
}

<!-- pages/index.vue -->
<script setup lang="ts">
const { t } = useI18n()

useSeoMeta({
  title: t('home.title'),
  description: t('home.description')
})
</script>

<template>
  <main>
    <h1>{{ $t('home.title') }}</h1>
    <p>{{ $t('home.description') }}</p>
  </main>
</template>

Nuxt automatically generates hreflang tags for /en, /fr, /de, /es versions of every page.

Query Parameters

Query parameters create duplicate content and waste crawl budget. Here's how to handle filters, sorting, and tracking params in Nuxt.

404 Pages

404 errors don't hurt SEO, but soft 404s do. Learn proper HTTP status codes, custom 404 design, and crawl budget optimization for Nuxt applications.

On this page

Quick Reference
Hreflang Format
Automatic Implementation with @nuxtjs/i18n
Manual Implementation
X-Default Tag
Hreflang Rules
Implementation Methods
Common Mistakes
Testing Hreflang
Full Example: Multilingual Nuxt App