RFC: Localization of pathnames and streamlining of navigation APIs

[amannn]

Localization of pathnames

Update: This is available as of [email protected], see the announcement thread.

We currently provide minimal documentation for localizing pathnames (see also the named routes example).

It would be helpful to have built-in support for this.

We could achieve this by accepting a route map:

// The `pathnames` object holds pairs of internal
// and external paths. Based on the locale, the
// corresponding external path will be picked.
const pathnames = {
  // If all locales use the same pathname, a single
  // external path can be used for all locales.
  '/': '/',
  '/blog': '/blog',
 
  // If locales use different paths, you can
  // specify each external path per locale.
  '/about': {
    en: '/about',
    de: '/ueber-uns'
  },
 
  // Dynamic params are supported via square brackets
  '/news/[articleSlug]-[articleId]': {
    en: '/news/[articleSlug]-[articleId]',
    de: '/neuigkeiten/[articleSlug]-[articleId]'
  }
};

Proposed docs:

• Middleware: Localizing pathnames
• New navigation docs

Prior art: https://v8.i18n.nuxtjs.org/guide/custom-paths

Streamlining of navigation APIs

Similar to the proposed factory function createLocalizedPathnamesNavigation, we could offer a createSharedPathnamesNavigation factory function that can be used to create the currently existing navigation APIs for non-localized pathnames.

This would:

1. Streamline all imports to a single namespace
2. Provide strict typing for the locales
3. Make it easier to upgrade from shared pathnames to localized pathnames (you'll have to adjust pathnames with dynamic params though, but we can provide TypeScript support here)

import {createSharedPathnamesNavigation} from 'next-intl/navigation';
 
export const locales = ['en', 'de'] as const;
 
export const {Link, redirect, usePathname, useRouter} =
  createSharedPathnamesNavigation({locales});

Potentially we could furthermore return a typed version of useLocale from these functions.

Rollout plan: Introduce createSharedPathnamesNavigation in a minor version, deprecate the previous imports and remove them in a major release.

[amannn]

See also vercel/next.js#49761

[amannn]

I've started working on a proof-of-concept for this!

[amannn]

Update: This is available as of [email protected], see the announcement thread.

[TommySorensen]

@amannn This really helps me removing my own version of this in my middleware 🎉
Could the pathnames be async so i potentially could fetch the list of url from a CMS one pr. minute?

[amannn]

@TommySorensen Great to hear! 🙌

The pathnames for the middleware can be fetched async if you compose the middleware.

As for the corresponding navigation APIs, you might not have a benefit there, because the point of them is really the static typing (which doesn't apply to your use case). How do you solve this currently? Do you provide wrappers for navigation APIs yourself that are based on CMS data?

[amannn]

This has been fully implemented in the 3.0 RC (see announcement)

[HarleySalas]

I'd imagine many people would use resource id's as their pathname key, as opposed to the default locale pathname. When getting dynamic data, a lot of cms api's will not let you query for a pathname that is different than the requested locale. Since it seems that rewrites are used, the param passed to a page component will only ever be the pathname's key and it fails to provide the localized pathname to the page params. When using default locale, it will often times ignore the localized pathname value and just display the pathname's object key. It seems like an optimistic assumption and in my opinion, would be much better to always prioritize the current locale, if available, rather than the pathname key.

tldr: I believe the pathname's key should never be shown in the url bar, if a localized version exists within the object.

[amannn]

@HarleySalas Do you think you could include some concrete examples that demonstrate your use case? It's a bit hard for me to follow since the terminology is quite broad.