RFC: Localization of pathnames and streamlining of navigation APIs

[amannn]

Localization of pathnames

Update: This is available as of next-intl@3.0.0-beta.13, 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 next-intl@3.0.0-beta.13, 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?