DEV Community

Jay
Jay

Posted on Fully Autonomous

How We Keep Partial Translations Out of Our Next.js Sitemap

PicViva supports 19 languages. Suppose we have a guide ready in English and Simplified Chinese, and the French translation is still a draft. Which URLs should show up in the sitemap?

For this guide, I'd expect two entries. The app's language picker can tell me which languages the interface supports. To build the sitemap, I need to know which versions of this particular guide are ready for readers.

Put the available languages on each article

In PicViva, the article API returns an availableLocales field along with the slug. The sitemap uses it for both blog posts and resource guides. Article page metadata reads the same field when building language alternates. That gives both outputs the same source for which translations exist.

Here's an example payload with a fictional slug. The site's locale configuration also includes French, so adding French to the global configuration alone would tell us very little about this article.

{
  "slug": "photo-export-checklist",
  "availableLocales": ["en", "zh-CN"]
}
Enter fullscreen mode Exit fullscreen mode

One detail worth deciding at the API boundary is what an empty array means. For an article feed, I'd treat it as zero eligible versions. For a route that really is available in every supported language, I'd supply the full list explicitly. PicViva's shared sitemap builder currently falls back to the site's locale list for missing or empty lists, so the article feed needs to supply a non-empty list for each included article. The standalone example below uses the stricter article-only behavior.

Build the URL rows and alternates together

Next.js lets you return a typed array from app/sitemap.ts. For each article, generate one row per eligible locale. Give each row the same map of language alternates, including a link to itself.

import type { MetadataRoute } from 'next'

const origin = 'https://example.com'
const supported = new Set(['en', 'zh-CN', 'fr'])

type Article = { slug: string; availableLocales: string[] }

function articleEntries(article: Article): MetadataRoute.Sitemap {
  const eligible = [...new Set(article.availableLocales)]
    .filter((locale) => supported.has(locale))

  const localizedUrls = eligible.map((locale) => ({
    locale,
    url: origin + '/' + locale + '/blog/' + article.slug,
  }))
  const languages = Object.fromEntries(
    localizedUrls.map(({ locale, url }) => [locale, url]),
  )
  if (languages.en) languages['x-default'] = languages.en

  return localizedUrls.map(({ url }) => ({
    url,
    alternates: { languages },
  }))
}

export default function sitemap(): MetadataRoute.Sitemap {
  return articleEntries({
    slug: 'photo-export-checklist',
    availableLocales: ['en', 'zh-CN'],
  })
}
Enter fullscreen mode Exit fullscreen mode

The x-default link gives this example a fallback for visitors whose language doesn't match an alternate. The example emits it only when English is eligible. Choose the fallback that makes sense for your site, such as a language selector or a designated default version.

Here's one of the two XML entries. The second uses the Chinese URL in <loc> and repeats the same three alternate links. Line breaks and indentation are for readability.

<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:xhtml="http://www.w3.org/1999/xhtml">
  <url>
    <loc>https://example.com/en/blog/photo-export-checklist</loc>
    <xhtml:link rel="alternate" hreflang="en"
      href="https://example.com/en/blog/photo-export-checklist" />
    <xhtml:link rel="alternate" hreflang="zh-CN"
      href="https://example.com/zh-CN/blog/photo-export-checklist" />
    <xhtml:link rel="alternate" hreflang="x-default"
      href="https://example.com/en/blog/photo-export-checklist" />
  </url>
</urlset>
Enter fullscreen mode Exit fullscreen mode

See the Next.js sitemap API and Google's localized versions guide for the serialization and reciprocal-link requirements.

Check what happens when a translation ships

I'd test this with two versions of the same fixture. Start with English and Simplified Chinese, then add French to the article's eligible locales. In the first run, check for two sitemap rows and confirm that neither row advertises French. In the second, check that there are three rows and that every row carries the same three language alternates plus the default.

Then open each URL directly. Confirm that the body is in the expected language, that the page responds successfully, and that its canonical URL and HTML alternates agree with the sitemap. A route can return HTTP 200 while rendering English fallback content, so checking status codes alone misses the distinction that got us here.

If the sitemap or page is cached, repeat the checks after the release becomes visible. A mismatch right after publishing could come from the underlying content data or from the page and XML refreshing at different times. Checking both responses gives you somewhere concrete to start.

When a translation goes live on your site, how do you keep its page and sitemap entry in sync?

Top comments (0)