[Feature] : Add Built-In getAlternates API for Generating Localized Alternate URLs

[bennajah]

I propose adding a built-in getAlternates helper to next-intl for generating localized alternate URLs with optional locale exclusion. This is a common pattern for building sitemaps, metadata alternates.languages, and SEO-friendly routing.

Suggested Implementation (Minimal)

type AlternatesProps = {
  host?: string;
  href: string | { pathname: string; query?: QueryParams };
  exclude?: Locale | Locale[];
};

export function getAlternates({ host = "", href, exclude }: AlternatesProps) {
  const excluded = Array.isArray(exclude) ? exclude : [exclude];

  const entries = routing.locales
    .filter((locale): locale is Locale => !excluded.includes(locale))
    .map((locale) => [locale, host + getPathname({ locale, href })]);

  return Object.fromEntries(entries) as Record<Locale, string>;
}

and we cant extract it from createNavigation API

import { createNavigation } from "next-intl/navigation";
import { routing } from "./routing";

export const {
  Link,
  ...
  getAlternates
} = createNavigation(routing);

Use Cases:

1. Generating Localized Sitemaps

import { routing } from "@/i18n/routing";
import { getAlternates } from "@/i18n/navigation";

export async function GET(): Promise<MetadataRoute.Sitemap> {
  const currentLocale = await getLocale();
  const pages = ["/about", "/pricing"];

  return pages.flatMap((href) =>
    routing.locales.map((locale) => ({
      url: getPathname({ locale, href }),
      alternates: getAlternates({ href, exclude: currentLocale }),
      lastModified: new Date(),
    }))
  );
}

2. Metadata Alternates (alternates.languages)

import { getAlternates } from "@/i18n/navigation";

export function async generateMetadata({ params }): Promise<Metadata> {
  const { locale } = await params;

  return {
    alternates: {
      languages: getAlternates({
        href: "/contact",
        host: "https://example.com",
        exclude: locale,
      }),
    },
  };
}

3. Showing Links to Translated Blog Posts

import { getAlternates } from "@/i18n/navigation";

export default function BlogPostPage({ params }) {
  const { locale, slug } = params;

  const alternateUrls = getAlternates({
    href: { pathname: "/blog/[slug]", query: { slug } },
    exclude: locale,
  });

  return (
    <aside>
      <h3>Read this article in other languages</h3>
      <ul>
        {Object.entries(alternateUrls).map(([altLocale, url]) => (
          <li key={altLocale}>
            <a href={url}>{altLocale.toUpperCase()}</a>
          </li>
        ))}
      </ul>
    </aside>
  );
}

[amannn]

Thanks for the snippets, I'm sure other developers will find them helpful!

As you've shown above, it really doesn't take that much code in userland to do this and people might still want to customize based on their needs. For the time being, I think exporting getPathname should be sufficient for this.

[bennajah]

When you use simple locale prefixes without domains or custom pathnames, the setup is straightforward.

But when you introduce domains + localized pathnames, you end up repeating the same information again in other places, especially for sitemaps, metadata, and alternate links.
That’s exactly why I requested this feature.

If we’ve already defined all domains and pathnames inside the routing config, we shouldn’t need to duplicate them somewhere else. Ideally, we would expose an API that returns alternates with fully-resolved URLs (domain + localized pathname). That way, sitemaps and metadata can reuse the routing config directly without repeating logic or risking inconsistencies.

Example:

import { defineRouting } from "next-intl/routing";
import { APP_DOMAIN, NEXT_LOCALE } from "@/lib/constants";

export const routing = defineRouting({
  locales: ["en-US", "fr-FR", "fr-CA", "en-CA"],
  defaultLocale: "en-US",
  localeCookie: {
    name: NEXT_LOCALE,
  },
  localePrefix: {
    mode: "as-needed",
    prefixes: {
      "fr-CA": "/fr",
      "en-CA": "/en",
    },
  },
  domains: [
    {
      defaultLocale: "en-US",
      domain: `us.${APP_DOMAIN}`,
      locales: ["en-US"],
    },
    {
      defaultLocale: "fr-FR",
      domain: `fr.${APP_DOMAIN}`,
      locales: ["fr-FR"],
    },
    {
      defaultLocale: "fr-CA",
      domain: `ca.${APP_DOMAIN}`,
      locales: ["fr-CA", "en-CA"],
    },
  ],
  pathnames: {
    "/": "/",
    "/about": {
      "fr-CA": "/a-propos",
      "fr-FR": "/a-propos",
    },
    "/contact": {
      "fr-CA": "/contactez-nous",
      "fr-FR": "/contactez-nous",
    },
  },
});

[amannn]

metadata

You can configure metadataBase to configure the domain in a shared place and then use getPathname to produce a result that can be used e.g. for canonical links.

alternate links

If you already specify these in the sitemap, there's no need to attach them again to every page.

[bennajah]

I created a custom utility that maps each locale to its correct domain.
This ensures that all generated URLs — including sitemap entries, canonical URLs, and alternate language URLs — always point to the right localized domain.

export function getDomain({ locale }: { locale: Locale }) {
  return routing.domains?.find((d) =>
    (d.locales as unknown as Locale[])?.includes(locale)
  )?.domain;
}

The sitemap reads the current domain and protocol from the request headers.
From this, it determines the active locale and generates properly localized URLs for all alternates:

import type { MetadataRoute } from "next";
import { headers } from "next/headers";
import { getDomain, getPathname } from "@/i18n/navigation";
import { routing } from "@/i18n/routing";

export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
 const domain = (await headers()).get("host");
 const protocol = (await headers()).get("x-forwarded-proto");
 const locale =
   routing.domains?.find((d) => d.domain === domain)?.defaultLocale ??
   routing.defaultLocale;

 return [
   {
     url: `${protocol}://${getDomain({ locale })}${getPathname({ locale, href: "/" })}`,
     lastModified: new Date(),
     alternates: {
       languages: Object.fromEntries(
         routing.locales.map((loc) => [
           loc,
           protocol +
             `://${getDomain({ locale: loc })}${getPathname({ locale: loc, href: "/" })}`,
         ])
       ),
     },
   },
 ];
}

The same domain-resolver function is used for metadata tags, ensuring consistent SEO output for:

export async function generateMetadata({
  params,
}: PageProps<"/[locale]">): Promise<Metadata> {
  const { locale } = (await params) as { locale: Locale };
  const protocol = (await headers()).get("x-forwarded-proto");
  const t = await getExtracted("Metadata");

  return {
    title: t("Home Page"),
    description: t("Welcome to our localized home page!"),
    alternates: {
      canonical: `${protocol}://${getDomain({ locale })}${getPathname({ locale, href: "/" })}`,
      languages: Object.fromEntries(
        routing.locales.map((loc) => [
          loc,
          `${protocol}://${getDomain({ locale: loc })}${getPathname({ locale: loc, href: "/" })}`,
        ])
      ),
    },
    openGraph: {
      url: `${protocol}://${getDomain({ locale })}${getPathname({ locale, href: "/" })}`,
      locale,
      alternateLocale: routing.locales.filter((loc) => loc !== locale),
    },
  };
}

so is there any better method to make sitemap return like this

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml">
<url>
  <loc>http://us.my-app.test</loc>
  <xhtml:link rel="alternate" hreflang="en-US" href="http://us.my-app.test" />
  <xhtml:link rel="alternate" hreflang="fr-FR" href="http://fr.my-app.test" />
  <xhtml:link rel="alternate" hreflang="fr-CA" href="http://ca.my-app.test" />
  <xhtml:link rel="alternate" hreflang="en-CA" href="http://ca.my-app.test/en" />
</url>
...
</urlset>

and for metadata return like this

<head>
  ...
  <link rel="canonical" href="http://us.my-app.test">
  <link rel="alternate" hreflang="en-US" href="http://us.my-app.test">
  <link rel="alternate" hreflang="fr-FR" href="http://fr.my-app.test">
  <link rel="alternate" hreflang="fr-CA" href="http://ca.my-app.test">
  <link rel="alternate" hreflang="en-CA" href="http://ca.my-app.test/en">
  ...
</head>