--- title: "Hreflang Tags in Nuxt" description: "Configure hreflang in Nuxt with useHead or @nuxtjs/i18n so Google shows the right language version instead of flagging duplicate content." canonical_url: "https://nuxtseo.com/learn-seo/nuxt/routes-and-rendering/i18n" last_updated: "2026-07-16" --- - Hreflang tags tell search engines which language or regional version of a page to serve, keeping localized content out of duplicate-content trouble - Every page in a hreflang cluster needs a self-referencing tag and must link back to every alternate version it references - Set `x-default` so visitors whose language doesn't match any configured version land somewhere sensible - `@nuxtjs/i18n` generates hreflang automatically for every configured locale, including return links and `x-default` 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](/learn-seo/nuxt/controlling-crawlers/duplicate-content) issues across languages. ```html ``` [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 ```ts [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 values combine an [ISO 639-1 language code](https://developers.google.com/search/docs/specialty/international/localized-versions) with an optional ISO 3166-1 Alpha-2 region code:
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 ```text 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` isn't a valid ISO 3166-1 region code: use `GB` for the United Kingdom instead. For Chinese, [Google's own hreflang examples](https://developers.google.com/search/docs/specialty/international/localized-versions) use `zh-TW` (the script is inferred as Traditional) or the explicit script codes `zh-Hant` and `zh-Hans`, since ISO 639-1 only defines one `zh` language code. ## Manual Implementation If you're not using @nuxtjs/i18n, set hreflang manually with `useHead()`: ```vue ``` Extract hreflang logic into a reusable composable at `composables/useHreflang.ts` rather than repeating it on every page: ```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: ```vue ``` ## Automatic Implementation with @nuxtjs/i18n 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. ```ts // 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: ```html ``` ### 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
```ts // 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: ```ts // 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: ```html ``` ## X-Default Tag The `x-default` hreflang provides a fallback URL when no language matches the user's preferences. [Google recommends setting it](https://developers.google.com/search/docs/specialty/international/localized-versions) whenever a hreflang cluster doesn't cover every possible visitor. ```html ``` Set x-default to: - Your primary language version - A language selector page - The most universally understood language version ```ts // 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' } ] }) ``` ## 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. [Missing return links](https://developers.google.com/search/docs/specialty/international/localized-versions) is one of the mistakes Google calls out directly. ```html ``` ### 2. Self-Referential Links Each page must include a hreflang tag pointing to itself: ```html ``` ### 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) A hreflang URL Google can't crawl or index gets dropped from the cluster, which breaks the return-link chain for every other page in it. ```vue ``` ### 4. Canonical vs Hreflang Canonical tags and hreflang serve different purposes: don't use canonical to point between language versions, since [that signals duplicate content](https://developers.google.com/search/docs/specialty/international/localized-versions) rather than translations. ```html ``` ```html ``` ## Server-Side Rendering Required Hreflang tags must exist in the initial HTML response. Setting them from `onMounted()` runs after the server has already sent its response, so search engines relying on the initial HTML never see them: ```vue ``` `useHead()` called in a component's setup function runs during SSR by default, so this is a risk if you defer the call into a lifecycle hook or a `.client.vue` component. ## Implementation Methods You can implement hreflang using HTML `` 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()`: ```vue ``` ### HTTP Headers Useful for non-HTML resources (PDFs, etc.). Configure in server routes: ```ts // 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 The [@nuxtjs/sitemap](https://nuxtseo.com/sitemap) module automatically generates hreflang annotations in sitemaps when used with @nuxtjs/i18n: ```ts // nuxt.config.ts export default defineNuxtConfig({ modules: ['@nuxtjs/sitemap', '@nuxtjs/i18n'], sitemap: { // Sitemap automatically includes hreflang from i18n config } }) ``` Generates: ```xml https://example.com/en https://example.com/fr ``` ## Common Mistakes ### Missing Return Links ```html ``` ### Non-Canonical URLs ```html ``` ### Noindex or Blocked Pages ```html ``` All pages in a hreflang cluster must be indexable and crawlable. Remove `noindex`, unblock the URL in `robots.txt`, or remove the page from hreflang annotations altogether. ### Mixing with Canonical ```html ``` ## 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](https://search.google.com/search-console) > International Targeting for errors: - Missing return tags - Incorrect language codes - Invalid URLs ### 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 Complete implementation with @nuxtjs/i18n: ```ts // 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' } } }) ``` ```json // locales/en.json { "home": { "title": "Welcome", "description": "Welcome to our site" } } ``` ```json // locales/fr.json { "home": { "title": "Bienvenue", "description": "Bienvenue sur notre site" } } ``` ```vue ``` ## Checklist - Every page includes a self-referencing hreflang tag plus links to all alternate versions - Every alternate page links back (return links) to close the cluster - `x-default` points to a sensible fallback for unmatched languages - Hreflang URLs return 200, are indexable, and aren't blocked by robots.txt - Canonical tags point to each page itself, never across language versions - Hreflang renders in the initial server response, not from `onMounted()` ## Localized Sitemaps The Nuxt Sitemap module emits hreflang alternates for every locale variant of a URL, so your `/en`, `/fr`, `/de`, and `/es` pages cross-reference correctly in the sitemap as well as the head: