Why layouts are risky for per-page metadata

In the Next.js App Router, metadata from a layout flows down to every page below it unless the page sets that field itself. The override is shallow: if a page sets alternates, its object replaces the layout's completely. If it doesn't, it silently inherits the layout's version. That is handy for a site name, and dangerous for anything that should be different on every URL, such as a canonical.

The bug, part one: alternates in the layout

Our [locale] layout built its alternates like this:

    alternates: {
      canonical: locale === 'en' ? 'https://www.lovecalcs.com/' : `https://www.lovecalcs.com/${locale}`,
      languages: Object.fromEntries(
        locales.map(loc => [loc, loc === 'en' ? 'https://www.lovecalcs.com/' : `https://www.lovecalcs.com/${loc}`])
      )
    },

That is correct for the homepage and wrong for everything else. The About, Contact, Terms and Privacy pages exported a static metadata object with a title and a description but no alternates, so they inherited this block. Their canonical pointed at the homepage, which a search engine reads as "this page is a duplicate of the homepage".

The bug, part two: hand-written tags in the head

The same layout also rendered hreflang links straight into its <head>:

        {/* Hreflang tags for SEO */}
        {locales.map((loc) => (
          <link
            key={loc}
            rel="alternate"
            hrefLang={loc}
            href={loc === 'en' ? 'https://www.lovecalcs.com/' : `https://www.lovecalcs.com/${loc}`}
          />
        ))}
        <link rel="alternate" hrefLang="x-default" href="https://www.lovecalcs.com/" />

JSX in a layout is not metadata, so no page can override it. Every page under the layout got these 12 homepage-pointing tags. The calculator and quiz pages, which already built correct per-page alternates in their own generateMetadata, ended up with two contradicting sets of hreflang in the same head.

The fix: one helper, used by every route

We deleted the hardcoded tags and replaced the layout's block with a single function that builds the canonical and alternates for any path:

export function buildAlternates(locale: string, path: string) {
  const clean = path === '/' ? '' : path;
  const url = (loc: string) =>
    loc === 'en' ? `${baseUrl}${clean || '/'}` : `${baseUrl}/${loc}${clean}`;

  const languages: Record<string, string> = {};
  for (const loc of locales) languages[loc] = url(loc);
  languages['x-default'] = url('en');

  return {
    canonical: url(locale),
    languages,
  };
}

path is the route without the locale, with '' for the homepage. English has no prefix, so its URLs are unprefixed and the English homepage keeps its trailing slash. Because every alternate is generated from the same locales array, the set is always complete, and every page links back to all of its siblings. That reciprocity is what hreflang depends on: an alternate that doesn't link back can be ignored.

The layout now calls buildAlternates(locale, ''), which is right for the homepage, and the pages that used to inherit it declare their own:

export async function generateMetadata({
  params,
}: {
  params: Promise<{ locale: string }>;
}): Promise<Metadata> {
  const { locale } = await params;
  return {
    // ...
    alternates: buildAlternates(locale, '/about'),
  };
}

The blog index and blog posts go through the same helper. The calculator and quiz pages kept their existing per-page code, which was only missing an x-default, so their fix was one line each:

  hreflangAlternates['x-default'] = 'https://www.lovecalcs.com/love-calculator';

Those pages use a relative canonical such as /love-calculator. That works because the root layout sets metadataBase: new URL('https://www.lovecalcs.com'), and Next.js resolves relative metadata URLs against it.

The rules it enforces

1. The canonical is self-referencing. /ja/about is canonical to itself, not to the English page. Translations are not duplicates, and pointing every translation's canonical at English asks search engines to treat them as duplicates.
2. Every page lists all 11 languages plus x-default, so each page has 12 alternates, including itself.
3. x-default points to English, which lives at the root with no prefix (/about, not /en/about).
4. Layout alternates are for the homepage only. Every other route sets its own, and nothing hreflang-related is hardcoded in a layout's JSX.

Sitemap alternates, kept in step

hreflang can also be declared in a sitemap. Ours is split into one sitemap per locale with generateSitemaps, and every entry lists its alternates:

  const localeUrl = (lang: string, route: string) =>
    lang === 'en' ? `${baseUrl}${route || '/'}` : `${baseUrl}/${lang}${route}`

  const staticEntries: MetadataRoute.Sitemap = routes.map((route) => ({
    url: localeUrl(locale, route),
    // ...
    alternates: {
      languages: Object.fromEntries(
        locales.map((lang) => [lang, localeUrl(lang, route)])
      ),
    },
  }))

Next.js renders alternates.languages as xhtml:link entries in the XML. Notice that localeUrl follows exactly the same rule as buildAlternates. That matters, because the sitemap and the page heads must agree. An earlier commit fixed exactly this kind of drift: the English sitemap URLs had used an /en/ prefix, and since English pages redirect to the unprefixed path, the sitemap was pointing crawlers at redirects. The sitemap entries don't include x-default; that one comes from the page heads.

The same fix commit also added export const revalidate = 3600 to the per-locale sitemaps and to the sitemap index. The home and calculator pages carry content that rotates daily, so their lastmod is today's UTC date, and without revalidation it would have been frozen at build time. Every other route reports a fixed date for its last real change, rather than claiming "modified now" on every crawl.

Common mistakes worth checking for

• hreflang or canonicals set in a shared layout, which is the bug above.
• Canonicals that point every translation at the default language.
• Mixed URL forms. /en/about against /about, or the bare domain against www. Production redirects the bare domain to www, and an earlier commit moved every hardcoded URL to www to avoid redirect chains. Every alternate should return a 200 directly.
• A missing x-default.
• Partial sets, where a page lists some languages but not all of them, so the return links don't match.

How to audit it

The quickest test is to fetch a deep page in a non-default language with curl and grep the HTML for rel="canonical" and rel="alternate". Try it on our About page in Japanese: you should see one canonical pointing at that exact URL, and 12 alternates pointing at the About page in each language plus x-default. If the homepage shows up on a page that isn't the homepage, you have this bug.

Then go one step further:

• Request each alternate URL and confirm it returns 200 without a redirect.
• Open one of the alternates and check that it lists the same 12 URLs.
• Compare the head tags with the xhtml:link entries in that locale's sitemap.
• In your search engine's webmaster tools, compare the canonical you declared with the one the search engine chose.

Takeaway

hreflang bugs are silent. Nothing breaks for users, so nobody notices. If your site is multilingual and uses nested layouts, check what each page inherits, not just what it declares.

The site in question is a free love calculator and compatibility test in 11 languages, if you want to see the tags for yourself.