Next.js 13 internationalized navigation

next-intl provides drop-in replacements for common Next.js navigation APIs that automatically handle the user locale behind the scenes.

Strategies

There are two strategies that you can use based on your needs:

1. Shared pathnames
2. Localized pathnames

Each strategy will provide you with corresponding navigation APIs that you can use in your components. Typically, you'll provide these APIs in a central module that you can easily reference (e.g. ./navigation.ts).

Strategy 1: Shared pathnames

The simplest case is when your app uses the same pathnames, regardless of the locale, e.g.:

• /en/about
• /en-GB/about

In this example, the path segment about remains the same, regardless of the user's locale. This is the simplest case, because the routes you define in Next.js will map directly to the URLs that a user can request.

To create navigation APIs for this use case, use the createSharedPathnamesNavigation function:

import {createSharedPathnamesNavigation} from 'next-intl/navigation';
 
export const {Link, redirect, usePathname, useRouter} =
  createSharedPathnamesNavigation({
    locales: ['en', 'en-GB'],
    pathnames: {
      '/': '/',
      '/about': {
        en: '/about',
        de: '/ueber-uns'
      }
    }
  });

The pathnames argument is identical to the configuration that you pass to the middleware for localizing pathnames. Because of this, you might want to share it along with the locales from a shared file like i18n.ts:

import {Pathnames} from 'next-intl/navigation';
 
export const locales = ['en', 'de'] as const;
 
export const pathnames: Pathnames<typeof locales> = {
  '/': '/',
  '/about': {
    en: '/about',
    de: '/ueber-uns'
  }
} as const;

Have a look at the App Router example to explore a working implementation of localized pathnames.

Strategy 2: Localized pathnames

If you've configured the middleware to use localized pathnames, you can use the createLocalizedPathnamesNavigation function to create corresponding navigation APIs:

're using the middleware configuration localized pathnames in the

Many apps choose to localize pathnames, especially when search engine optimization is relevant:

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

APIs

Link

This component wraps next/link (opens in a new tab) and automatically prefixes the href with the current locale as necessary. If the default locale is matched, the href remains unchanged and no prefix is added.

import {Link} from '../navigation';
 
// When the user is on `/en`, the link will point to `/en/about`
<Link href="/about">About</Link>
 
// You can override the `locale` to switch to another language
<Link href="/" locale="de">Switch to German</Link>
 
// Dynamic params need to be interpolated into the pathname
<Link href="/users/12">Susan</Link>

useRouter

If you need to navigate programmatically, e.g. in an event handler, next-intl provides a convience API that wraps useRouter from Next.js (opens in a new tab) and automatically applies the locale of the user.

'use client';
 
import {useRouter} from '../navigation';
 
const router = useRouter();
 
// When the user is on `/en`, the router will navigate to `/en/about`
router.push('/about');
 
// You can override the `locale` to switch to another language
router.replace('/about', {locale: 'de'});
 
// Dynamic params need to be interpolated into the pathname
router.push('/users/12', {locale: 'de'});
 

'use client';
 
import {usePathname, useRouter} from '../navigation';
 
const pathname = usePathname();
const router = useRouter();
 
router.replace(pathname, {locale: 'de'});

usePathname

To retrieve the pathname without a potential locale prefix, you can call usePathname.

'use client';
 
import {usePathname} from '../navigation';
 
// When the user is on `/en`, this will be `/`
const pathname = usePathname();

redirect

If you want to interrupt the render and redirect to another page, you can invoke the redirect function. This wraps the redirect function from Next.js (opens in a new tab) and automatically applies the current locale.

import {redirect} from '../navigation';
 
// When the user is on `/en/profile`, this will be `/en/login`
redirect('/login');
 
// Dynamic params need to be interpolated into the pathname
router.push('/users/12');