fix(seo): warn when a domain setup has no locale to annotate as x-default (#4092)

Author: BobbieGoede

docs/content/docs/02.guide/10.multi-domain-locales.md

@@ -9,6 +9,7 @@ How to set up multi domain locales:
 - Configure the `locales` option as an array of objects:
   - Each object has a `domains` key whose value is a array of the domains you'd like to use for that locale. Optionally include a port (if non-standard) and/or a protocol. If the protocol is not provided then an attempt will be made to auto-detect it but that might not work correctly in some cases like when the pages are statically generated.
   - Optionally set for each object a `defaultForDomains` key whose value is a array of the default domains you'd like to use for that locale. Optionally include a port (if non-standard) and/or a protocol. If the protocol is not provided then an attempt will be made to auto-detect it but that might not work correctly in some cases like when the pages are statically generated.
+- Optionally set `defaultLocale`. Each domain resolves its own unprefixed locale from `defaultForDomains`, this names the fallback for the cluster as a whole - see [`defaultLocale` and `x-default`](#defaultlocale-and-x-default).
 - Optionally set `detectBrowserLanguage` to `false`{lang="ts"}. When enabled (which it is by default), a first visit can be redirected to the locale detected from the browser, within the current domain. Set to `false`{lang="ts"} if you want to ensure that visiting a given domain always shows the page in that domain's own locale.
 
 ```ts [nuxt.config.ts]
@@ -51,6 +52,7 @@ export default defineNuxtConfig({
         domains: i18nDomains
       },
     ],
+    defaultLocale: 'en',
     multiDomainLocales: true
   }
 })
@@ -213,3 +215,9 @@ Given the above configuration, following requests will be:
 Locales served on other domains stay available in `locales` and in the locale switcher, `switchLocalePath` links to them on the domain that serves them. Browser language detection only applies locales served on the current domain, so a visitor whose browser or cookie locale isn't available there keeps that domain's own locale.
 
 A request on a host that doesn't match any configured domain, such as a staging domain or a health check by IP, isn't restricted. Every locale is served there and `defaultLocale` is used as the unprefixed default, so it's worth setting even when every domain has its own default through `defaultForDomains`.
+
+## `defaultLocale` and `x-default`
+
+The domains are annotated as one cluster, each page links to its alternates on the other domains. A cluster has a single fallback for unmatched languages, so the `x-default` alternate is taken from `defaultLocale` rather than from the locale a domain happens to default to - otherwise every domain would name a different one.
+
+`defaultLocale` is optional here, since each domain resolves its own unprefixed locale through `defaultForDomains`. Leaving it out means no `x-default` is annotated at all, which is allowed but drops a signal for visitors whose language matches none of your locales. A warning is logged when it isn't set.

src/runtime/routing/head.ts

@@ -12,6 +12,18 @@ function patchHead(head: ComposableContext['head'] | undefined, input: I18nHeadM
   head?.patch(input)
 }
 
+/**
+ * Alternate links annotate the domains as one cluster, and a cluster has a single fallback for
+ * unmatched languages. It cannot be resolved from the current domain - every domain would name a
+ * different one - so `x-default` is left out until `defaultLocale` names it.
+ */
+export function missesClusterFallback(ctx: ComposableContext, config: Required<I18nHeadOptions>): boolean {
+  const { domains, hreflangLinks, defaultLocale } = ctx.routingOptions
+  return !!config.seo && domains && hreflangLinks && !defaultLocale
+}
+
+let warnedClusterFallback = false
+
 function createHeadContext(
   ctx: ComposableContext,
   config: Required<I18nHeadOptions>,
@@ -25,6 +37,11 @@ function createHeadContext(
   // deduplicate, layered configs merge `canonicalQueries` arrays with duplicate entries
   const canonicalQueries = [...new Set((typeof config.seo === 'object' && config.seo?.canonicalQueries) || [])]
 
+  if (import.meta.dev && !warnedClusterFallback && missesClusterFallback(ctx, config)) {
+    warnedClusterFallback = true
+    console.warn('[nuxt-i18n] Set `defaultLocale` to annotate an `x-default` alternate for your domains.')
+  }
+
   if (!baseUrl && !ctx.routingOptions.domains) {
     if (ctx.strictSeo) {
       throw new Error('I18n `baseUrl` is required to generate valid SEO tag links.')

test/routing-head.test.ts

@@ -3,9 +3,10 @@ import { nextTick } from 'vue'
 import { createMemoryHistory, createRouter } from 'vue-router'
 import { createRoutingContext } from '../src/runtime/routing/context'
 import { setupMultiDomainLocales } from '../src/runtime/routing/domain'
-import { _useLocaleHead, _useSetI18nParams, localeHead } from '../src/runtime/routing/head'
+import { _useLocaleHead, _useSetI18nParams, localeHead, missesClusterFallback } from '../src/runtime/routing/head'
 import { switchLocalePath } from '../src/runtime/routing/routing'
 import { headEntries } from './mocks/imports'
+import { resolveDefaultLocale } from '../src/runtime/shared/locales'
 
 import type { Router } from 'vue-router'
 import type { ComposableContext } from '../src/runtime/composable-context'
@@ -30,7 +31,7 @@ const routes = [
   })),
 )
 
-function createTestContext(initialLocale = 'en', strictSeo = false, domains = false) {
+function createTestContext(initialLocale = 'en', strictSeo = false, domains = false, configuredDefault = 'en') {
   let locale = initialLocale
   const router = createRouter({ history: createMemoryHistory(), routes })
   const head = { patches: [] as I18nHeadMetaInfo[], patch(val: I18nHeadMetaInfo) { this.patches.push(val) } }
@@ -43,10 +44,12 @@ function createTestContext(initialLocale = 'en', strictSeo = false, domains = fa
     // rebuild the route table for the current host, mirrors the runtime plugin
     setupMultiDomainLocales(initialLocale, 'prefix_except_default', router)
   }
+  const host = domains ? `${initialLocale}.example.com` : 'example.com'
   const ctx = {
     ...createRoutingContext({
       router,
-      defaultLocale: 'en',
+      // resolved the way the runtime plugin does, rather than supplied
+      defaultLocale: resolveDefaultLocale(host, configuredDefault, domains ? domainLocales : locales),
       strategy: 'prefix_except_default',
       routing: true,
       domains,
@@ -65,7 +68,13 @@ function createTestContext(initialLocale = 'en', strictSeo = false, domains = fa
     metaState: { htmlAttrs: {}, meta: [], link: [] },
     seoSettings: { dir: true, lang: true, seo: true },
     localePathPayload: {},
-    routingOptions: { defaultLocale: 'en', strictCanonicals: true, hreflangLinks: true, domains },
+    routingOptions: {
+      // `createComposableContext` feeds `x-default` the configured value, not the host's default
+      defaultLocale: configuredDefault || '',
+      strictCanonicals: true,
+      hreflangLinks: true,
+      domains,
+    },
   } as unknown as ComposableContext
   return { router, ctx, head, setLocale: (l: string) => (locale = l) }
 }
@@ -147,6 +156,40 @@ describe('localeHead with domains', () => {
       ['og:locale:alternate', 'nl_NL'],
     ])
   })
+
+  test('every domain annotates the same `x-default`', async () => {
+    for (const host of ['en', 'fr', 'nl']) {
+      const { router, ctx } = createTestContext(host, false, true)
+      await router.push('/')
+
+      const xDefault = localeHead(ctx, {}).link.find(x => x.hreflang === 'x-default')
+      expect(xDefault?.href).toBe('https://en.example.com')
+    }
+  })
+
+  test('a missing cluster fallback is only worth reporting where alternates are emitted', () => {
+    const seo = { dir: true, lang: true, seo: true }
+    const withDomains = (configuredDefault: string) => createTestContext('fr', false, true, configuredDefault).ctx
+
+    expect(missesClusterFallback(withDomains(''), seo)).toBe(true)
+    // `defaultLocale` names the fallback
+    expect(missesClusterFallback(withDomains('en'), seo)).toBe(false)
+    // no alternate links to annotate
+    expect(missesClusterFallback(withDomains(''), { ...seo, seo: false })).toBe(false)
+    // a single domain cluster resolves `x-default` from the routing default as before
+    expect(missesClusterFallback(createTestContext('fr', false, false, '').ctx, seo)).toBe(false)
+  })
+
+  test('no configured `defaultLocale` annotates no fallback, rather than one per domain', async () => {
+    // the domain default is host-resolved and would disagree across the cluster, `prepareOptions`
+    // warns instead - a locale has no way to claim the cluster fallback on its own
+    const { router, ctx } = createTestContext('fr', false, true, '')
+    await router.push('/')
+
+    const links = localeHead(ctx, {}).link
+    expect(links.filter(x => x.hreflang === 'x-default')).toEqual([])
+    expect(links.map(x => x.hreflang ?? x.rel)).toContain('fr')
+  })
 })
 
 describe('switchLocalePath', () => {