feat!: experimental strict internal i18n head management (#3638)

Author: BobbieGoede

docs/content/docs/02.guide/90.migrating.md

@@ -28,6 +28,17 @@ definePageMeta({
 </script>
 ```
 
+### Experimental strict SEO mode
+We have added a new experimental option `strictSeo`{lang="yml"} that enables strict SEO mode, which changes the way i18n head tags are handled. 
+
+With strict SEO mode enabled, the i18n head tags are managed internally, this allows for some much requested improvements:
+* The module will no longer add alternate tags for unsupported locales when setting localized dynamic route params.
+* Unsupported locale links used with `<SwitchLocalePathLink>`{lang="vue"} are disabled, their links will be set to `'#'`{lang="ts"} and will have a `data-i18n-disabled`{lang="vue"} attribute for styling purposes.
+* The `useLocaleHead()`{lang="ts"} is no longer needed in strict SEO mode, i18n tags are automatically set by the module and usage will throw an error.
+* Canonical query parameters are configured globally with `experimental.strictSeo.canonicalQueryParams`{lang="yml"}.
+* The `useSetI18nParams()`{lang="ts"} inherits the global canonical query parameter config which can be overridden through its options parameter.
+
+If this mode proves stable it will become the default in v11, please try it out and report any issues you encounter.
 
 ### Lazy loading
 The `lazy` option has been removed and lazy loading of locale messages is now the default behavior.
@@ -36,8 +47,8 @@ The `lazy` option has been removed and lazy loading of locale messages is now th
 The function signature for `finalizePendingLocaleChange()`{lang="ts"} has been corrected from `() => Promise<void>`{lang="ts-type"} to `() => void`{lang="ts-type"}.
 This change was made since the function does not rely on any async operations and should not be awaited, and should prevent unnecessary function coloring.
 
-### Default arguments changed `useLocaleHead()`{lang="ts"} and `$localeHead()`{lang="ts"}
-The default value for the `key` property has been changed from `'hid'` to `'key'`.
+### Arguments changed `useLocaleHead()`{lang="ts"} and `$localeHead()`{lang="ts"}
+The `key` property has been removed and can no longer be configured, this is necessary for predictable and consistent localized head tag management.
 
 ### `restructureDir` migration path removed
 To ease migration in v9 it was possible to disable the new directory structure by setting `restructureDir: false`, this has now been removed and we recommend using the default value of `'i18n'`.

docs/content/docs/04.api/00.options.md

@@ -480,6 +480,12 @@ This feature relies on [Nuxt's `experimental.typedRoutes`](https://nuxt.com/docs
 This functionality is only supported for projects using vite.
 ::
 
+## `strictSeo`
+
+- type: `boolean | SeoAttributesOptions`{lang="ts-type"}
+- default: `false`{lang="ts"}
+- Enables strict SEO mode.
+
 ## customBlocks
 
 Configure the `i18n` custom blocks of SFC.

pnpm-lock.yaml

@@ -1,4 +1,4 @@
-import { describe, test, expect } from 'vitest'
+import { test, expect } from 'vitest'
 import { $fetch, url } from './utils'
 import {
   assertLocaleHeadWithDom,
@@ -142,7 +142,7 @@ export function basicUsageTests() {
     )
 
     expect(await page.locator('#locale-head').innerText()).toMatchInlineSnapshot(
-      `"{ "htmlAttrs": { "lang": "en" }, "link": [ { "key": "i18n-xd", "rel": "alternate", "href": "http://localhost:3000/nuxt-context-extension", "hreflang": "x-default" }, { "key": "i18n-alt-en", "rel": "alternate", "href": "http://localhost:3000/nuxt-context-extension", "hreflang": "en" }, { "key": "i18n-alt-fr", "rel": "alternate", "href": "http://localhost:3000/fr/nuxt-context-extension", "hreflang": "fr" }, { "key": "i18n-alt-ja", "rel": "alternate", "href": "http://localhost:3000/ja/nuxt-context-extension", "hreflang": "ja" }, { "key": "i18n-alt-ja-JP", "rel": "alternate", "href": "http://localhost:3000/ja/nuxt-context-extension", "hreflang": "ja-JP" }, { "key": "i18n-alt-nl", "rel": "alternate", "href": "http://localhost:3000/nl/nuxt-context-extension", "hreflang": "nl" }, { "key": "i18n-alt-nl-NL", "rel": "alternate", "href": "http://localhost:3000/nl/nuxt-context-extension", "hreflang": "nl-NL" }, { "key": "i18n-alt-nl-BE", "rel": "alternate", "href": "http://localhost:3000/be/nuxt-context-extension", "hreflang": "nl-BE" }, { "key": "i18n-alt-kr", "rel": "alternate", "href": "http://localhost:3000/kr/nuxt-context-extension", "hreflang": "kr" }, { "key": "i18n-alt-kr-KO", "rel": "alternate", "href": "http://localhost:3000/kr/nuxt-context-extension", "hreflang": "kr-KO" }, { "key": "i18n-can", "rel": "canonical", "href": "http://localhost:3000/nuxt-context-extension" } ], "meta": [ { "key": "i18n-og-url", "property": "og:url", "content": "http://localhost:3000/nuxt-context-extension" }, { "key": "i18n-og", "property": "og:locale", "content": "en" }, { "key": "i18n-og-alt-fr", "property": "og:locale:alternate", "content": "fr" }, { "key": "i18n-og-alt-ja-JP", "property": "og:locale:alternate", "content": "ja_JP" }, { "key": "i18n-og-alt-nl-NL", "property": "og:locale:alternate", "content": "nl_NL" }, { "key": "i18n-og-alt-nl-BE", "property": "og:locale:alternate", "content": "nl_BE" }, { "key": "i18n-og-alt-kr-KO", "property": "og:locale:alternate", "content": "kr_KO" } ] }"`
+      `"{ "htmlAttrs": { "lang": "en" }, "link": [ { "id": "i18n-xd", "rel": "alternate", "href": "http://localhost:3000/nuxt-context-extension", "hreflang": "x-default" }, { "id": "i18n-alt-en", "rel": "alternate", "href": "http://localhost:3000/nuxt-context-extension", "hreflang": "en" }, { "id": "i18n-alt-fr", "rel": "alternate", "href": "http://localhost:3000/fr/nuxt-context-extension", "hreflang": "fr" }, { "id": "i18n-alt-ja", "rel": "alternate", "href": "http://localhost:3000/ja/nuxt-context-extension", "hreflang": "ja" }, { "id": "i18n-alt-ja-JP", "rel": "alternate", "href": "http://localhost:3000/ja/nuxt-context-extension", "hreflang": "ja-JP" }, { "id": "i18n-alt-nl", "rel": "alternate", "href": "http://localhost:3000/nl/nuxt-context-extension", "hreflang": "nl" }, { "id": "i18n-alt-nl-NL", "rel": "alternate", "href": "http://localhost:3000/nl/nuxt-context-extension", "hreflang": "nl-NL" }, { "id": "i18n-alt-nl-BE", "rel": "alternate", "href": "http://localhost:3000/be/nuxt-context-extension", "hreflang": "nl-BE" }, { "id": "i18n-alt-kr", "rel": "alternate", "href": "http://localhost:3000/kr/nuxt-context-extension", "hreflang": "kr" }, { "id": "i18n-alt-kr-KO", "rel": "alternate", "href": "http://localhost:3000/kr/nuxt-context-extension", "hreflang": "kr-KO" }, { "id": "i18n-can", "rel": "canonical", "href": "http://localhost:3000/nuxt-context-extension" } ], "meta": [ { "id": "i18n-og-url", "property": "og:url", "content": "http://localhost:3000/nuxt-context-extension" }, { "id": "i18n-og", "property": "og:locale", "content": "en" }, { "id": "i18n-og-alt-fr", "property": "og:locale:alternate", "content": "fr" }, { "id": "i18n-og-alt-ja-JP", "property": "og:locale:alternate", "content": "ja_JP" }, { "id": "i18n-og-alt-nl-NL", "property": "og:locale:alternate", "content": "nl_NL" }, { "id": "i18n-og-alt-nl-BE", "property": "og:locale:alternate", "content": "nl_BE" }, { "id": "i18n-og-alt-kr-KO", "property": "og:locale:alternate", "content": "kr_KO" } ] }"`
     )
   })
 
@@ -426,14 +426,16 @@ export function basicUsageTests() {
     // head tags - alt links are updated server side
     const html = await $fetch('/?noncanonical&canonical')
     const dom = getDom(html)
-    expect(dom.querySelector('#i18n-alt-fr')?.getAttribute('href')).toEqual('http://localhost:3000/fr?canonical=')
+    expect(dom.querySelector('link[id=i18n-alt-fr]')?.getAttribute('href')).toEqual(
+      'http://localhost:3000/fr?canonical='
+    )
   })
 
   test('respects `experimental.alternateLinkCanonicalQueries`', async () => {
     // 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')?.getAttribute('href')).toEqual(
+    expect(product1Dom.querySelector('link[id=i18n-alt-nl]')?.getAttribute('href')).toEqual(
       'http://localhost:3000/nl/products/grote-stoel?canonical=123'
     )
     expect(product1Dom.querySelector('#switch-locale-path-link-nl')?.getAttribute('href')).toEqual(
@@ -442,7 +444,7 @@ export function basicUsageTests() {
 
     const product2Html = await $fetch('/nl/products/rode-mok?test=123&canonical=123')
     const product2dom = getDom(product2Html)
-    expect(product2dom.querySelector('#i18n-alt-en')?.getAttribute('href')).toEqual(
+    expect(product2dom.querySelector('link[id=i18n-alt-en]')?.getAttribute('href')).toEqual(
       'http://localhost:3000/products/red-mug?canonical=123'
     )
     expect(product2dom.querySelector('#switch-locale-path-link-en')?.getAttribute('href')).toEqual(
@@ -454,7 +456,7 @@ export function basicUsageTests() {
     // head tags - alt links are updated server side
     const product1Html = await $fetch('/products/big-chair')
     const product1Dom = getDom(product1Html)
-    expect(product1Dom.querySelector('#i18n-alt-nl')?.getAttribute('href')).toEqual(
+    expect(product1Dom.querySelector('link[id=i18n-alt-nl]')?.getAttribute('href')).toEqual(
       'http://localhost:3000/nl/products/grote-stoel'
     )
     expect(product1Dom.querySelector('#switch-locale-path-link-nl')?.getAttribute('href')).toEqual(
@@ -463,7 +465,7 @@ export function basicUsageTests() {
 
     const product2Html = await $fetch('/nl/products/rode-mok')
     const product2dom = getDom(product2Html)
-    expect(product2dom.querySelector('#i18n-alt-en')?.getAttribute('href')).toEqual(
+    expect(product2dom.querySelector('link[id=i18n-alt-en]')?.getAttribute('href')).toEqual(
       'http://localhost:3000/products/red-mug'
     )
     expect(product2dom.querySelector('#switch-locale-path-link-en')?.getAttribute('href')).toEqual('/products/red-mug')
@@ -511,35 +513,35 @@ export function basicUsageTests() {
   test('dynamic parameters', async () => {
     const { page } = await renderPage('/products/big-chair')
 
-    expect(await page.locator('#nuxt-locale-link-nl').getAttribute('href')).toEqual('/nl/products/grote-stoel')
+    expect(await page.locator('#switch-locale-path-link-nl').getAttribute('href')).toEqual('/nl/products/grote-stoel')
 
     await gotoPath(page, '/nl/products/rode-mok')
     await page.waitForFunction(
-      () => document.querySelector('#nuxt-locale-link-en')?.getAttribute('href') === '/products/red-mug'
+      () => document.querySelector('#switch-locale-path-link-en')?.getAttribute('href') === '/products/red-mug'
     )
-    expect(await page.locator('#nuxt-locale-link-en').getAttribute('href')).toEqual('/products/red-mug')
+    expect(await page.locator('#switch-locale-path-link-en').getAttribute('href')).toEqual('/products/red-mug')
 
     // Translated params are not lost on query changes
     await page.locator('#params-add-query').clickNavigate()
     await page.waitForURL(url('/nl/products/rode-mok?test=123&canonical=123'))
-    expect(await page.locator('#nuxt-locale-link-en').getAttribute('href')).toEqual(
+    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').clickNavigate()
     await page.waitForURL(url('/nl/products/rode-mok'))
-    expect(await page.locator('#nuxt-locale-link-en').getAttribute('href')).toEqual('/products/red-mug')
+    expect(await page.locator('#switch-locale-path-link-en').getAttribute('href')).toEqual('/products/red-mug')
 
     // head tags - alt links are updated server side
     const product1Html = await $fetch('/products/big-chair')
     const product1Dom = getDom(product1Html)
-    expect(product1Dom.querySelector('#i18n-alt-nl')?.getAttribute('href')).toEqual(
+    expect(product1Dom.querySelector('link[id=i18n-alt-nl]')?.getAttribute('href')).toEqual(
       'http://localhost:3000/nl/products/grote-stoel'
     )
 
     const product2Html = await $fetch('/nl/products/rode-mok')
     const product2dom = getDom(product2Html)
-    expect(product2dom.querySelector('#i18n-alt-en')?.getAttribute('href')).toEqual(
+    expect(product2dom.querySelector('link[id=i18n-alt-en]')?.getAttribute('href')).toEqual(
       'http://localhost:3000/products/red-mug'
     )
   })

specs/basic-usage-tests.ts

@@ -0,0 +1,64 @@
+import { test, expect, describe } from 'vitest'
+import { fileURLToPath } from 'node:url'
+import { $fetch, setup, url } from '../utils'
+import { getDom, getHeadSnapshot, renderPage } from '../helper'
+
+await setup({
+  rootDir: fileURLToPath(new URL(`../fixtures/basic_usage`, import.meta.url)),
+  browser: true,
+  // prerender: true,
+  // overrides
+  nuxtConfig: {
+    i18n: {
+      experimental: {
+        strictSeo: true
+      }
+    }
+  }
+})
+
+describe('experimental.strictSeo', async () => {
+  test('dynamic parameters rendered correctly during SSR', async () => {
+    const { page } = await renderPage('/')
+    await page.goto(url('/products/big-chair'))
+    expect(await page.locator('#switch-locale-path-link-nl').getAttribute('href')).toEqual('/nl/products/grote-stoel')
+    expect(await getHeadSnapshot(page)).toMatchInlineSnapshot(`
+      "HTML:
+        lang: en
+        dir: ltr
+      Link:
+        canonical: http://localhost:3000/products/big-chair
+        alternate[x-default]: http://localhost:3000/products/big-chair
+        alternate[en]: http://localhost:3000/products/big-chair
+        alternate[fr]: http://localhost:3000/fr/products/french-chair
+        alternate[ja]: http://localhost:3000/ja/products/japanese-chair
+        alternate[ja-JP]: http://localhost:3000/ja/products/japanese-chair
+        alternate[nl]: http://localhost:3000/nl/products/grote-stoel
+        alternate[nl-NL]: http://localhost:3000/nl/products/grote-stoel
+      Meta:
+        og:url: http://localhost:3000/products/big-chair
+        og:locale: en
+        og:locale:alternate: fr, ja, ja_JP, nl, nl_NL"
+    `)
+
+    await page.goto(url('/nl/products/rode-mok'))
+    expect(await page.locator('#switch-locale-path-link-en').getAttribute('href')).toEqual('/products/red-mug')
+    expect(await page.locator('#switch-locale-path-link-ja[data-i18n-disabled]').getAttribute('href')).toEqual('#')
+    expect(await getHeadSnapshot(page)).toMatchInlineSnapshot(`
+      "HTML:
+        lang: nl-NL
+        dir: ltr
+      Link:
+        canonical: http://localhost:3000/nl/products/rode-mok
+        alternate[x-default]: http://localhost:3000/products/red-mug
+        alternate[en]: http://localhost:3000/products/red-mug
+        alternate[fr]: http://localhost:3000/fr/products/french-mug
+        alternate[nl]: http://localhost:3000/nl/products/rode-mok
+        alternate[nl-NL]: http://localhost:3000/nl/products/rode-mok
+      Meta:
+        og:url: http://localhost:3000/nl/products/rode-mok
+        og:locale: nl_NL
+        og:locale:alternate: en, fr, nl"
+    `)
+  })
+})

specs/experimental/experimental_seo.spec.ts

@@ -7,7 +7,7 @@ import LangSwitcher from '../components/LangSwitcher.vue'
 
 const { t, locale } = useI18n()
 const localePath = useLocalePath()
-const i18nHead = useLocaleHead({ key: 'id', seo: { canonicalQueries: ['page'] } })
+const i18nHead = useLocaleHead({ seo: { canonicalQueries: ['page'] } })
 const { data, refresh } = useAsyncData(`home-${locale.value}`, () =>
   Promise.resolve({
     aboutPath: localePath('about'),

specs/fixtures/basic/pages/index.vue

@@ -30,4 +30,11 @@ section {
 .my-leave-active {
   opacity: 0;
 }
+
+a[data-i18n-disabled] {
+  /* display: none; */
+  color: #d54141;
+  pointer-events: none;
+  user-select: none;
+}
 </style>

specs/fixtures/basic_usage/app.vue

@@ -13,7 +13,7 @@ const localesExcludingCurrent = computed(() => {
 
 <template>
   <div>
-    <section id="lang-switcher-with-nuxt-link">
+    <section v-if="!$nuxt.$config.public.i18n.experimental.strictSeo" id="lang-switcher-with-nuxt-link">
       <strong>Using <code>NuxtLink</code></strong
       >:
       <NuxtLink