Managing canonical links

[markomitranic]

I've been going over the docs and found the example of managing canonical links as part of Next's metadata: https://next-intl-docs.vercel.app/docs/routing/navigation#getpathname

import {getPathname} from '../navigation';
 
export async function generateMetadata({params: {locale}}) {
  return {
    alternates: {
      canonical: '/' + locale + getPathname({
        locale,
        href: {
          pathname: '/users/[userId]',
          params: {userId: '5'}
        }
      })
    }
  };
}

Let's look at two problems i see with it:

1. Shared paths also need a way to get a canonical URL. None is documented as the section is about getPathname, not about canonical links. I wish we had a documented way to do this.
2. The example at hand seems incorrect. It hardcodes a locale prefix, which may not be correct because we can have prefixless locales or domain based locales. I would have expected there to be a function that can generate a url based on params, much like Link interenally does. The getPathname doesn't serve that purpose as it always results in a no-locale version of the URL, regardless of which locale I ask it to give me.

I suppose, if we had a function similar to getPathname that would instead return an URL based on the given params, that would solve both of these cases easily. What does Link use internally? Also we could document this use case if we had a clear answer, that'd be awesome!

Sidenote: According to Google's docs each language is its own canonical URL except in rare, manually managed cases:
> "Different language versions of a single page are considered duplicates only if the primary content is in the same language...."

[amannn]

2. The example at hand seems incorrect. It hardcodes a locale prefix, which may not be correct because we can have prefixless locales or domain based locales. I would have expected there to be a function that can generate a url based on params, much like Link interenally does. The getPathname doesn't serve that purpose as it always results in a no-locale version of the URL, regardless of which locale I ask it to give me.

Note that the example is about this use case: "This can for example be useful to retrieve a canonical link for a page that accepts search params."

It's probably a bit easy to miss, I've added a code comment in 38f305d — hope this helps!

I suppose, if we had a function similar to getPathname that would instead return an URL based on the given params, that would solve both of these cases easily.

This is unfortunately not supported in Next.js, at least not without tradeoffs: vercel/next.js#43704

Sidenote: According to Google's docs each language is its own canonical URL except in rare, manually managed cases:

"Different language versions of a single page are considered duplicates only if the primary content is in the same language...."

Yep, canonical links shouldn't be used for connecting localized pages. Instead, alternate links should be used (which is what next-intl does).

[amannn]

Ah, you're using localized pathnames? I thought you didn't since you've mentioned:

Shared paths also need a way to get a canonical URL.

… in the initial post. Well yes, if it's just about adding the locale prefix, I'll agree with you. I've mentioned this just yesterday here: #779. It'd be a breaking change for getPathname though, so maybe something for the next major version. For the time being, you can add the prefix manually as illustrated in the docs.

[markomitranic]

Ah I get your meaning. Well both methods need a way for us to define a canonical URL. Meaning both methods, lack the same functionality - a public interface for adding (or not adding) a locale prefix to a path.

Yes in both cases we can do it manually with '/' + params.locale + ... but that is wonky. It doesn't work with localePrefix: "as-needed" or domains for example. We have already clearly defined rules within next-intl and I wish to use those same rules to properly add locales to paths, instead of writing the same logic in my pages.

I'd say that either getPathname needs to be updated, which is a breaking change, or we need a new one that is prefix-aware and can give us both absolute and relative link strings. That would also work in shared pathnames wouldn't it?

[markomitranic]

Actually, now that I think about it, you already have a system that does percisely this, entirely on the server side:

Link:
<http://localhost:3000/>; rel="alternate"; hreflang="en-DK",
<http://localhost:3000/da-DK>; rel="alternate"; hreflang="da-DK",
<http://localhost:3000/>; rel="alternate"; hreflang="x-default"

Why can't we utilize the exact same system in our user-space code to get these values as strings or objects?

[amannn]

Ah yes, I think we're on the same page now—thank you for explaining!

I've updated #444 to incorporate your feedback, I think this is a push in a good direction where the navigation APIs will become more useful in general.

[markomitranic]

I wanted to provide another very basic example that should be totally expected. Here i wish to construct a banal list of URLs, for example a language switcher, as an entirely server-side component.

For the sake of simplicity I've used a hardcoded path, but in reality we'd probably see unstable_setRequestLocale and generateStaticParams.

export default async function Page() {
  const links = locales.map((locale) => {
    const url = getPathname({ href: "/test", locale });
    return { locale, url };
  });

  return (
    <ul>
      {links.map(({ locale, url }, key) => {
        return (<li key={key}>{locale}: {url}</li>);
      })}
    </ul>
  );
}

Expected output:

en-GB: /test
da-DK: /da-DK/test

Actual output:

en-GB: /test
da-DK: /test

The conclusion here is that getPathname is not sufficient as it does not serve the purpose of resolving the actual URL that is to be used - it resolves the pathname. We have no alternative to resolve the actual URL, except Link which results in an element, not a string && is a client component.

You can extrapolate this example further - what if this isn't a tsx file at all, and I wish to do this in an API or a cronjob?

return Response.json(locales.map((locale) => {
  const url = getPathname({ href: "/test", locale });
  return { locale, url };
}));

It is clear from the Link headers that we are perfectly able to get the needed information to generate a string URL on the server, and as a string. I'd like to get the same utility functions that enable this type of "static resolution" of urls.

[amannn]

Yep, I agree—currently, you have to apply prefixes and potentially a domain yourself to the result of getPathname. I hope that can act as a workaround for you until #444 lands.

[markomitranic]

Yep, writing that logic as we speak :) just wanted to provide another example of why this should be a part of the library.

[amannn]

A quick note here: getPathname has been fixed to include a potential locale prefix as part of an upcoming createNavigation function (currently available as a prerelease here: #1391). In case you decide to give it a spin, let me know if everything works as expected for you!

Also, thanks again for the great feedback here! 🙏❤️

[SalahAdDin]

Does this package extend the default metadata function to include the canonical and alternate parameters?

export const metadata = {
  alternates: {
    canonical: 'https://nextjs.org',
    languages: {
      'en-US': 'https://nextjs.org/en-US',
      'de-DE': 'https://nextjs.org/de-DE',
    },
    media: {
      'only screen and (max-width: 600px)': 'https://nextjs.org/mobile',
    },
    types: {
      'application/rss+xml': 'https://nextjs.org/rss',
    },
  },
}

[markomitranic]

Both of them are my own functions, meaning you would be expected to make your own according to your project's needs.

• safeLocale a type guard that casts a value into a Locale enum at runtime. Thus ensuring we never work with an unsupported value.
• getAlternateUrls a function that is able to figure out what our urls should be for other languages, using getPathname from next-intl internally.

I have some special logic in my code, allowing for use of multiple domains and language identifiers, so I've had to wrap getPathname into my own logic. You might be able to use it directly, I guess.

[SalahAdDin]

Well, getAlternateUrl is not clear to me.

Also, as we are getting the from the backend, our case requires another approach.

[markomitranic]

getAlternateUrls is just a function that wraps getPathname and calls it in a loop for each locale, there isn't much to it. If you know how to use getPathname then you also know how to use it in a loop to create links for all locales.

Such a function is also where you'd do any additional, custom work that you want to do. For example, apart from looping, I also fetch stuff from the CMS, and decide if a requested page exists in a given language. I also perform additional URL rewrites. You can do whatever you wanna do.

Needless to say, getPathname is a backend function, and getting metadata is a backend only task, so not sure I understand your point about backend somehow being different than... backend.

[SalahAdDin]

I don't know how to use getPathname, where is it required?

For example:

/**
 * Receive a base url and a set of locale based paths and generate the alternate links:
 *
 * @example {href: "https://lorem.com", paths: {locale: `${category}/article`}}
 * @param props
 * @returns a set of locale based alternated links
 */
export const getAlternateUrls = ({ href, paths }: GetAlternateUrlsArgs) =>
  Object.entries(paths).reduce(
    (acc, [locale, path]) => ({
      ...acc,
      locale: `${href}/${locale}/${path}`,
    }),
    {}
  );

We get all possible alternatives to the link from the backend or with another function, we built the alternate URL with the base URL, the locale, and the path, and it should work.

Where should I use getPathname here?

[markomitranic]

You can find the getPathname docs here https://next-intl-docs.vercel.app/docs/routing/navigation#getpathname

To answer your question "where should you use it" it depends on what you wish to do, it is entirely your decision. What I do is i loop over locales, and then query the CMS/DB/PIM for each locale to see if a given entity exists. Then I use it's data with import { getPathname } from "~/navigation"; find out more here.

For each language, I invoke the getPathname function, and ask it to generate a path for that entity. Arguments differ depending on which route you are targeting - for example /src/app/[lang]/page.tsx has no arguments (or just query args) while /src/app/[lang]/[id]/page.tsx will require an id parameter. @amannn did awesome work to make it type-hint correctly. What I get back is a possibly translated route, with the ID of the entity in that other language, and the only remaining part is for me to decide how to apply a locale tag. For you it seems to be a prefix, for me its a combination of a domain and a prefix.

Hope that clarifies it - it is up to you, not next-intl :P

Here are some examples of how I use getPathname:

getPathname({
      href: { pathname: "/", query: params.query },
      locale: params.locale ?? params.currentLocale,
    });

getPathname(
      href: {
        pathname: "/[...page]",
        params: {
          page: [params.slug],
        },
        query: params.query,
      },
      locale: params.locale ?? params.currentLocale,
    });

getPathname({
      href: {
        pathname: "/shop/[category]",
        params: {
          category: params.categoryId,
        },
        query: params.query,
      },
      locale: params.locale ?? params.currentLocale,
    });

getPathname({
      href: {
        pathname: "/shop/[category]/[sku]",
        params: {
          category: params.categoryId,
          sku: params.sku,
        },
        query: params.query,
      });