feat: opt-in alternate link consistency (#3320)

divine · BobbieGoede · web-flow · commit 16d8e1839d67 · 2025-02-06T09:20:04.000+01:00
Co-authored-by: Bobbie Goede &lt;bobbiegoede@gmail.com&gt;
diff --git a/docs/content/docs/4.api/0.options.md b/docs/content/docs/4.api/0.options.md
@@ -511,6 +511,12 @@ This feature relies on [Nuxt's `experimental.typedRoutes`](https://nuxt.com/docs
 Changing this will also change the paths in `locales` returned by `useI18n()`{lang="ts"}.
 ::
 
+### `alternateLinkCanonicalQueries`
+
+- type: `boolean`{lang="ts-type"}
+- default: `false`{lang="ts"}
+- Whether to remove non-canonical query parameters from alternate link meta tags
+
 ## customBlocks
 
 Configure the `i18n` custom blocks of SFC.
diff --git a/specs/basic_usage.spec.ts b/specs/basic_usage.spec.ts
@@ -28,7 +28,10 @@ describe('basic usage', async () => {
           i18n: {
             baseUrl: 'http://localhost:3000',
             skipSettingLocaleOnNavigate: undefined,
-            detectBrowserLanguage: undefined
+            detectBrowserLanguage: undefined,
+            experimental: {
+              alternateLinkCanonicalQueries: false
+            }
           }
         }
       }
@@ -415,13 +418,35 @@ describe('basic usage', async () => {
       }
     })
 
-    const html = await $fetch('/?noncanonical')
+    const html = await $fetch('/?noncanonical&canonical')
     const dom = getDom(html)
     await assertLocaleHeadWithDom(dom, '#home-use-locale-head')
 
     const links = getDataFromDom(dom, '#home-use-locale-head').link
     const i18nCan = links.find(x => x.id === 'i18n-can')
     expect(i18nCan.href).toContain(configDomain)
+    expect(dom.querySelector('#i18n-alt-fr').href).toEqual(
+      'https://runtime-config-domain.com/fr?noncanonical&canonical'
+    )
+
+    await restore()
+  })
+
+  test('render seo tags with `experimental.alternateLinkCanonicalQueries`', async () => {
+    const restore = await startServerWithRuntimeConfig({
+      public: {
+        i18n: {
+          experimental: {
+            alternateLinkCanonicalQueries: true
+          }
+        }
+      }
+    })
+
+    // head tags - alt links are updated server side
+    const html = await $fetch('/?noncanonical&canonical')
+    const dom = getDom(html)
+    expect(dom.querySelector('#i18n-alt-fr').href).toEqual('http://localhost:3000/fr?canonical=')
 
     await restore()
   })
@@ -468,8 +493,10 @@ describe('basic usage', async () => {
 
     // Translated params are not lost on query changes
     await page.locator('#params-add-query').click()
-    await waitForURL(page, '/nl/products/rode-mok?test=123')
-    expect(await page.locator('#nuxt-locale-link-en').getAttribute('href')).toEqual('/products/red-mug?test=123')
+    await waitForURL(page, '/nl/products/rode-mok?test=123&canonical=123')
+    expect(await page.locator('#nuxt-locale-link-en').getAttribute('href')).toEqual(
+      '/products/red-mug?test=123&canonical=123'
+    )
 
     await page.locator('#params-remove-query').click()
     await waitForURL(page, '/nl/products/rode-mok')
diff --git a/specs/basic_usage_compat_4.spec.ts b/specs/basic_usage_compat_4.spec.ts
@@ -28,7 +28,10 @@ describe('basic usage - compatibilityVersion: 4', async () => {
           i18n: {
             baseUrl: 'http://localhost:3000',
             skipSettingLocaleOnNavigate: undefined,
-            detectBrowserLanguage: undefined
+            detectBrowserLanguage: undefined,
+            experimental: {
+              alternateLinkCanonicalQueries: false
+            }
           }
         }
       }
@@ -415,13 +418,35 @@ describe('basic usage - compatibilityVersion: 4', async () => {
       }
     })
 
-    const html = await $fetch('/?noncanonical')
+    const html = await $fetch('/?noncanonical&canonical')
     const dom = getDom(html)
     await assertLocaleHeadWithDom(dom, '#home-use-locale-head')
 
     const links = getDataFromDom(dom, '#home-use-locale-head').link
     const i18nCan = links.find(x => x.id === 'i18n-can')
     expect(i18nCan.href).toContain(configDomain)
+    expect(dom.querySelector('#i18n-alt-fr').href).toEqual(
+      'https://runtime-config-domain.com/fr?noncanonical&canonical'
+    )
+
+    await restore()
+  })
+
+  test('render seo tags with `experimental.alternateLinkCanonicalQueries`', async () => {
+    const restore = await startServerWithRuntimeConfig({
+      public: {
+        i18n: {
+          experimental: {
+            alternateLinkCanonicalQueries: true
+          }
+        }
+      }
+    })
+
+    // head tags - alt links are updated server side
+    const html = await $fetch('/?noncanonical&canonical')
+    const dom = getDom(html)
+    expect(dom.querySelector('#i18n-alt-fr').href).toEqual('http://localhost:3000/fr?canonical=')
 
     await restore()
   })
@@ -468,8 +493,10 @@ describe('basic usage - compatibilityVersion: 4', async () => {
 
     // Translated params are not lost on query changes
     await page.locator('#params-add-query').click()
-    await waitForURL(page, '/nl/products/rode-mok?test=123')
-    expect(await page.locator('#nuxt-locale-link-en').getAttribute('href')).toEqual('/products/red-mug?test=123')
+    await waitForURL(page, '/nl/products/rode-mok?test=123&canonical=123')
+    expect(await page.locator('#nuxt-locale-link-en').getAttribute('href')).toEqual(
+      '/products/red-mug?test=123&canonical=123'
+    )
 
     await page.locator('#params-remove-query').click()
     await waitForURL(page, '/nl/products/rode-mok')
diff --git a/specs/experimental/switch_locale_path_link_ssr.spec.ts b/specs/experimental/switch_locale_path_link_ssr.spec.ts
@@ -1,7 +1,7 @@
 import { test, expect, describe } from 'vitest'
 import { fileURLToPath } from 'node:url'
 import { $fetch, setup } from '../utils'
-import { getDom, gotoPath, renderPage, waitForURL } from '../helper'
+import { getDom, gotoPath, renderPage, startServerWithRuntimeConfig, waitForURL } from '../helper'
 
 await setup({
   rootDir: fileURLToPath(new URL(`../fixtures/basic_usage`, import.meta.url)),
@@ -12,13 +12,15 @@ await setup({
     runtimeConfig: {
       public: {
         i18n: {
-          baseUrl: ''
+          baseUrl: '',
+          alternateLinkCanonicalQueries: false
         }
       }
     },
     i18n: {
       experimental: {
-        switchLocalePathLinkSSR: true
+        switchLocalePathLinkSSR: true,
+        alternateLinkCanonicalQueries: false
       }
     }
   }
@@ -35,14 +37,45 @@ describe('experimental.switchLocalePathLinkSSR', async () => {
 
     // Translated params are not lost on query changes
     await page.locator('#params-add-query').click()
-    await waitForURL(page, '/nl/products/rode-mok?test=123')
-    expect(await page.locator('#switch-locale-path-link-en').getAttribute('href')).toEqual('/products/red-mug?test=123')
+    await waitForURL(page, '/nl/products/rode-mok?test=123&canonical=123')
+    expect(await page.locator('#switch-locale-path-link-en').getAttribute('href')).toEqual(
+      '/products/red-mug?test=123&canonical=123'
+    )
 
     await page.locator('#params-remove-query').click()
     await waitForURL(page, '/nl/products/rode-mok')
     expect(await page.locator('#switch-locale-path-link-en').getAttribute('href')).toEqual('/products/red-mug')
   })
 
+  test('respects `experimental.alternateLinkCanonicalQueries`', async () => {
+    const restore = await startServerWithRuntimeConfig({
+      public: {
+        i18n: {
+          experimental: {
+            switchLocalePathLinkSSR: true,
+            alternateLinkCanonicalQueries: true
+          }
+        }
+      }
+    })
+
+    // head tags - alt links are updated server side
+    const product1Html = await $fetch('/products/big-chair?test=123&canonical=123')
+    const product1Dom = getDom(product1Html)
+    expect(product1Dom.querySelector('#i18n-alt-nl').href).toEqual('/nl/products/grote-stoel?canonical=123')
+    expect(product1Dom.querySelector('#switch-locale-path-link-nl').href).toEqual(
+      '/nl/products/grote-stoel?test=123&canonical=123'
+    )
+
+    const product2Html = await $fetch('/nl/products/rode-mok?test=123&canonical=123')
+    const product2dom = getDom(product2Html)
+    expect(product2dom.querySelector('#i18n-alt-en').href).toEqual('/products/red-mug?canonical=123')
+    expect(product2dom.querySelector('#switch-locale-path-link-en').href).toEqual(
+      '/products/red-mug?test=123&canonical=123'
+    )
+    await restore()
+  })
+
   test('dynamic parameters rendered correctly during SSR', async () => {
     // head tags - alt links are updated server side
     const product1Html = await $fetch('/products/big-chair')
diff --git a/specs/fixtures/basic_usage/layouts/default.vue b/specs/fixtures/basic_usage/layouts/default.vue
@@ -5,7 +5,7 @@ import { useI18n, useLocaleHead } from '#i18n'
 
 const route = useRoute()
 const { t } = useI18n()
-const head = useLocaleHead({ key: 'id', seo: { canonicalQueries: ['page'] } })
+const head = useLocaleHead({ key: 'id', seo: { canonicalQueries: ['page', 'canonical'] } })
 const title = computed(() => `Page - ${t(route.meta?.title ?? '')}`)
 </script>
 
diff --git a/specs/fixtures/basic_usage/nuxt.config.ts b/specs/fixtures/basic_usage/nuxt.config.ts
@@ -22,6 +22,7 @@ export default defineNuxtConfig({
     locales: ['en', 'fr'],
     defaultLocale: 'en',
     experimental: {
+      alternateLinkCanonicalQueries: false,
       autoImportTranslationFunctions: true
     }
     // debug: true,
diff --git a/specs/fixtures/basic_usage/pages/index.vue b/specs/fixtures/basic_usage/pages/index.vue
@@ -61,7 +61,7 @@ definePageMeta({
   alias: ['/aliased-home-path']
 })
 
-const i18nHead = useLocaleHead({ key: 'id', seo: { canonicalQueries: ['page'] } })
+const i18nHead = useLocaleHead({ key: 'id', seo: { canonicalQueries: ['page', 'canonical'] } })
 useHead(() => ({
   htmlAttrs: {
     lang: i18nHead.value.htmlAttrs!.lang
diff --git a/specs/fixtures/basic_usage/pages/products.vue b/specs/fixtures/basic_usage/pages/products.vue
@@ -16,7 +16,9 @@ onMounted(async () => {
     <LangSwitcher />
     <ul>
       <li>
-        <NuxtLink id="params-add-query" :to="localePath({ query: { test: '123' } })">Add query</NuxtLink>
+        <NuxtLink id="params-add-query" :to="localePath({ query: { test: '123', canonical: '123' } })"
+          >Add query</NuxtLink
+        >
       </li>
       <li>
         <NuxtLink id="params-remove-query" :to="localePath({ query: undefined })">Remove query</NuxtLink>
diff --git a/specs/fixtures/basic_usage/pages/products/[slug].vue b/specs/fixtures/basic_usage/pages/products/[slug].vue
@@ -6,7 +6,7 @@ const product = ref()
 const { locale } = useI18n()
 const route = useRoute()
 
-const setI18nParams = useSetI18nParams()
+const setI18nParams = useSetI18nParams({ canonicalQueries: ['canonical'] })
 product.value = await $fetch(`/api/products/${route.params.slug}`)
 if (product.value != null) {
   const availableLocales = Object.keys(product.value.slugs)
diff --git a/specs/fixtures/basic_usage_compat_4/app/layouts/default.vue b/specs/fixtures/basic_usage_compat_4/app/layouts/default.vue
@@ -5,7 +5,7 @@ import { useI18n, useLocaleHead } from '#i18n'
 
 const route = useRoute()
 const { t } = useI18n()
-const head = useLocaleHead({ key: 'id', seo: { canonicalQueries: ['page'] } })
+const head = useLocaleHead({ key: 'id', seo: { canonicalQueries: ['page', 'canonical'] } })
 const title = computed(() => `Page - ${t(route.meta?.title ?? '')}`)
 </script>
 
diff --git a/specs/fixtures/basic_usage_compat_4/app/pages/index.vue b/specs/fixtures/basic_usage_compat_4/app/pages/index.vue
@@ -61,7 +61,7 @@ definePageMeta({
   alias: ['/aliased-home-path']
 })
 
-const i18nHead = useLocaleHead({ key: 'id', seo: { canonicalQueries: ['page'] } })
+const i18nHead = useLocaleHead({ key: 'id', seo: { canonicalQueries: ['page', 'canonical'] } })
 useHead(() => ({
   htmlAttrs: {
     lang: i18nHead.value.htmlAttrs!.lang
diff --git a/specs/fixtures/basic_usage_compat_4/app/pages/products.vue b/specs/fixtures/basic_usage_compat_4/app/pages/products.vue
@@ -16,7 +16,9 @@ onMounted(async () => {
     <LangSwitcher />
     <ul>
       <li>
-        <NuxtLink id="params-add-query" :to="localePath({ query: { test: '123' } })">Add query</NuxtLink>
+        <NuxtLink id="params-add-query" :to="localePath({ query: { test: '123', canonical: '123' } })"
+          >Add query</NuxtLink
+        >
       </li>
       <li>
         <NuxtLink id="params-remove-query" :to="localePath({ query: undefined })">Remove query</NuxtLink>
diff --git a/specs/fixtures/basic_usage_compat_4/app/pages/products/[slug].vue b/specs/fixtures/basic_usage_compat_4/app/pages/products/[slug].vue
@@ -6,7 +6,7 @@ const product = ref()
 const { locale } = useI18n()
 const route = useRoute()
 
-const setI18nParams = useSetI18nParams()
+const setI18nParams = useSetI18nParams({ canonicalQueries: ['canonical'] })
 product.value = await $fetch(`/api/products/${route.params.slug}`)
 if (product.value != null) {
   const availableLocales = Object.keys(product.value.slugs)
diff --git a/specs/fixtures/basic_usage_compat_4/nuxt.config.ts b/specs/fixtures/basic_usage_compat_4/nuxt.config.ts
@@ -23,6 +23,7 @@ export default defineNuxtConfig({
     vueI18n: './config/i18n.config.ts',
     defaultLocale: 'en',
     experimental: {
+      alternateLinkCanonicalQueries: false,
       autoImportTranslationFunctions: true,
       localeDetector: './localeDetector.ts'
     },
diff --git a/src/constants.ts b/src/constants.ts
@@ -32,7 +32,8 @@ export const DEFAULT_OPTIONS = {
     autoImportTranslationFunctions: false,
     typedPages: true,
     typedOptionsAndMessages: false,
-    generatedLocaleFilePathFormat: 'absolute'
+    generatedLocaleFilePathFormat: 'absolute',
+    alternateLinkCanonicalQueries: false
   },
   bundle: {
     compositionOnly: true,
diff --git a/src/runtime/composables/index.ts b/src/runtime/composables/index.ts
@@ -93,7 +93,7 @@ export function useSetI18nParams(seo?: SeoAttributesOptions): SetI18nParamsFunct
 
       // prettier-ignore
       metaObject.link.push(
-        ...getHreflangLinks(common, locales, key),
+        ...getHreflangLinks(common, locales, key, seo),
         ...getCanonicalLink(common, key, seo)
       )
 
diff --git a/src/runtime/routing/head.ts b/src/runtime/routing/head.ts
diff --git a/src/types.ts b/src/types.ts

Original file line number	Diff line number	Diff line change
`@@ -22,6 +22,7 @@ export default defineNuxtConfig({`
`22`	`22`	`locales: ['en', 'fr'],`
`23`	`23`	`defaultLocale: 'en',`
`24`	`24`	`experimental: {`
	`25`	`+ alternateLinkCanonicalQueries: false,`
`25`	`26`	`autoImportTranslationFunctions: true`
`26`	`27`	`}`
`27`	`28`	`// debug: true,`
Original file line number	Diff line number	Diff line change
`@@ -93,7 +93,7 @@ export function useSetI18nParams(seo?: SeoAttributesOptions): SetI18nParamsFunct`
`93`	`93`
`94`	`94`	`// prettier-ignore`
`95`	`95`	`metaObject.link.push(`
`96`		`- ...getHreflangLinks(common, locales, key),`
	`96`	`+ ...getHreflangLinks(common, locales, key, seo),`
`97`	`97`	`...getCanonicalLink(common, key, seo)`
`98`	`98`	`)`
`99`	`99`