Routing

next-intl integrates with the routing system of Next.js in two places:

1. Middleware: Negotiates the locale and handles redirects & rewrites (e.g. / → /en)
2. Navigation APIs: Lightweight wrappers around Next.js’ navigation APIs like <Link />

This enables you to express your app in terms of APIs like <Link href="/about">, while aspects like the locale and user-facing pathnames are automatically handled behind the scenes (e.g. /de/ueber-uns).

defineRouting

The routing configuration that is shared between the middleware and the navigation APIs can be defined with the defineRouting function.

import {defineRouting} from 'next-intl/routing';
 
export const routing = defineRouting({
  // A list of all locales that are supported
  locales: ['en', 'de'],
 
  // Used when no locale matches
  defaultLocale: 'en'
});

Depending on your routing needs, you may wish to consider further settings—see below.

localePrefix

By default, the pathnames of your app will be available under a prefix that matches your directory structure (e.g. /en/about → app/[locale]/about/page.tsx). You can however adapt the routing to optionally remove the prefix or customize it per locale by configuring the localePrefix setting.

localePrefix: 'always' (default)

By default, pathnames always start with the locale (e.g. /en/about).

import {defineRouting} from 'next-intl/routing';
 
export const routing = defineRouting({
  // ...
  localePrefix: 'always'
});

localePrefix: 'as-needed'

If you want to use no prefix for the default locale (e.g. /about) while keeping it for other locales (e.g. /de/about), you can configure your routing accordingly:

import {defineRouting} from 'next-intl/routing';
 
export const routing = defineRouting({
  // ...
  localePrefix: 'as-needed'
});

Note that:

1. If you use this routing strategy, make sure that your middleware matcher detects unprefixed pathnames.
2. The middleware will by default set a cookie to remember the user’s locale preference. If no explicit locale prefix is present in the pathname, then locale detection will potentially redirect users to the latest locale that was matched based on the cookie value (e.g. / → /de).
3. If a superfluous locale prefix like /en/about is requested, the middleware will automatically redirect to the unprefixed version /about. This can be helpful in case you’re redirecting from another locale and you want to update a potential cookie value first (e.g. <Link /> relies on this mechanism).

localePrefix: 'never'

If you’d like to provide a locale to next-intl, e.g. based on user settings, you can consider setting up next-intl without i18n routing. This way, you don’t need to use the routing integration in the first place.

However, you can also configure the middleware to never show a locale prefix in the URL, which can be helpful in the following cases:

1. You want to use domain-based routing and have only one locale per domain
2. You want to use a cookie to determine the locale while enabling static rendering

import {defineRouting} from 'next-intl/routing';
 
export const routing = defineRouting({
  // ...
  localePrefix: 'never'
});

In this case, requests for all locales will be rewritten to have the locale only prefixed internally. You still need to place all your pages inside a [locale] folder for the routes to be able to receive the locale param.

Note that:

1. If you use this routing strategy, make sure that your middleware matcher detects unprefixed pathnames.
2. Alternate links are disabled in this mode since URLs might not be unique per locale. Due to this, consider including these yourself, or set up a sitemap that links localized pages via alternates.
3. You can consider increasing the maxAge attribute of the locale cookie to a longer duration to remember the user’s preference across sessions.

prefixes

If you’d like to customize the user-facing prefix, you can provide a locale-based mapping:

import {defineRouting} from 'next-intl/routing';
 
export const routing = defineRouting({
  locales: ['en-US', 'de-AT', 'zh'],
  defaultLocale: 'en-US',
  localePrefix: {
    mode: 'always',
    prefixes: {
      'en-US': '/us',
      'de-AT': '/eu/at'
      // (/zh will be used as-is)
    }
  }
});

Note that:

1. You should adapt your middleware matcher to match the custom prefixes.
2. Custom prefixes are only visible to the user and rewritten internally to the corresponding locale. Therefore, the [locale] segment corresponds to the locale, not the prefix.

import {useLocale} from 'next-intl';
 
function Component() {
  // Assuming the locale is 'en-US'
  const locale = useLocale();
 
  // Extracts the "US" region
  const {region} = new Intl.Locale(locale);
}

pathnames

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

Example:

• /en/about
• /de/ueber-uns

Since you typically want to define these routes only once internally, you can use the next-intl middleware to rewrite such incoming requests to shared pathnames.

import {defineRouting} from 'next-intl/routing';
 
export const routing = defineRouting({
  locales: ['en-US', 'en-UK', 'de'],
  defaultLocale: 'en-US',
 
  // The `pathnames` object holds pairs of internal and
  // external paths. Based on the locale, the external
  // paths are rewritten to the shared, internal ones.
  pathnames: {
    // If all locales use the same pathname, a single
    // external path can be used for all locales
    '/': '/',
    '/blog': '/blog',
 
    // If some locales use different paths, you can
    // specify the relevant external pathnames
    '/about': {
      de: '/ueber-uns'
    },
 
    // Dynamic params are supported via square brackets
    '/news/[articleSlug]': {
      de: '/neuigkeiten/[articleSlug]'
    },
 
    // Static pathnames that overlap with dynamic segments
    // will be prioritized over the dynamic segment
    '/news/just-in': {
      de: '/neuigkeiten/aktuell'
    },
 
    // Also (optional) catch-all segments are supported
    '/categories/[...slug]': {
      de: '/kategorien/[...slug]'
    }
  }
});

Localized pathnames map to a single internal pathname that is created via the file-system based routing in Next.js. In the example above, /de/ueber-uns will be handled by the page at /[locale]/about/page.tsx.

app
└── [locale]
    └── news
        └── [slug]

import {defineRouting} from 'next-intl/routing';
 
export const routing = defineRouting({
  locales: ['en', 'de'],
  defaultLocale: 'en',
  pathnames: {
    '/news/[slug]': {
      en: '/news/[slug]',
      de: '/neuigkeiten/[slug]'
    }
  }
});

// Statically generated at build time
revalidatePath('/de/news/some-article');
 
// Dynamically generated at runtime:
revalidatePath('/de/neuigkeiten/some-article');

/en/news/launch-of-new-product-94812
/de/neuigkeiten/produktneuheit-94812

import {notFound} from 'next';
import {Locale} from 'next-intl';
import {fetchContent} from './cms';
 
type Props = {
  params: Promise<{
    locale: Locale;
    slug: Array<string>;
  }>;
};
 
export default async function CatchAllPage({params}: Props) {
  const {locale, slug} = await params;
  const content = await fetchContent(locale, slug);
  if (!content) notFound();
 
  // ...
}

domains

If you want to serve your localized content based on different domains, you can provide a list of mappings between domains and locales via the domains setting.

Examples:

• us.example.com: en-US
• ca.example.com: en-CA
• ca.example.com/fr: fr-CA
• fr.example.com: fr-FR

In many cases, domains are combined with a localePrefix setting to achieve results as shown above. Also custom prefixes can be used to customize the user-facing prefix per locale.

import {defineRouting} from 'next-intl/routing';
 
export const routing = defineRouting({
  locales: ['en-US', 'en-CA', 'fr-CA', 'fr-FR'],
  defaultLocale: 'en-US',
  domains: [
    {
      domain: 'us.example.com',
      defaultLocale: 'en-US',
      locales: ['en-US']
    },
    {
      domain: 'ca.example.com',
      defaultLocale: 'en-CA',
      locales: ['en-CA', 'fr-CA']
    },
    {
      domain: 'fr.example.com',
      defaultLocale: 'fr-FR',
      locales: ['fr-FR']
    }
  ],
  localePrefix: {
    mode: 'as-needed',
    prefixes: {
      // Cleaner prefix for `ca.example.com/fr`
      'fr-CA': '/fr'
    }
  }
});

Locales are required to be unique across domains, therefore regional variants are typically used to avoid conflicts. Note however that you don’t necessarily need to provide messages for each locale if the overall language is sufficient for your use case.

If no domain matches, the middleware will fall back to the general defaultLocale (e.g. on localhost).

import {defineRouting} from 'next-intl/routing';
 
const isDev = process.env.NODE_ENV === 'development';
 
export const routing = defineConfig({
  // ...
  domains: [
    {
      domain: isDev ? 'localhost:3000' : 'us.example.com'
      // ...
    },
    {
      domain: isDev ? 'localhost:3001' : 'ca.example.com'
      // ...
    }
  ]
});

# Like `us.example.com`
PORT=3000 npm run dev
 
# Like `ca.example.com`
PORT=3001 npm run dev

import {defineRouting} from 'next-intl/routing';
 
const isUsDomain =
  process.env.VERCEL_PROJECT_PRODUCTION_URL === 'us.example.com';
 
export const routing = defineRouting({
  locales: isUsDomain ? ['en-US'] : ['en-CA', 'fr-CA'],
  defaultLocale: isUsDomain ? 'en-US' : 'en-CA',
  localePrefix: isUsDomain ? 'never' : 'always'
});

localeDetection

The middleware will detect a matching locale based on your routing configuration & the incoming request and will either pass the request through for a matching locale or redirect to one that matches.

If you want to rely entirely on the URL to resolve the locale, you can set the localeDetection property to false. This will disable locale detection based on the accept-language header and a potentially existing cookie value from a previous visit.

import {defineRouting} from 'next-intl/routing';
 
export const routing = defineRouting({
  // ...
  localeDetection: false
});

In this case, only the locale prefix and a potentially matching domain are used to determine the locale.

localeCookie

If a user changes the locale to a value that doesn’t match the accept-language header, next-intl will set a session cookie called NEXT_LOCALE that contains the most recently detected locale. This is used to remember the user’s locale preference for subsequent requests.

By default, the cookie will be configured with the following attributes:

2. sameSite: This value is set to lax so that the cookie can be set when coming from an external site.
3. path: This value is not set by default, but will use the value of your basePath if configured.

If you have more specific requirements, you can adjust these settings accordingly:

import {defineRouting} from 'next-intl/routing';
 
export const routing = defineRouting({
  // ...
 
  // Will be merged with the defaults
  localeCookie: {
    // Custom cookie name
    name: 'USER_LOCALE',
    // Expire in one year
    maxAge: 60 * 60 * 24 * 365
  }
});

… or turn the cookie off entirely:

import {defineRouting} from 'next-intl/routing';
 
export const routing = defineRouting({
  // ...
 
  localeCookie: false
});

alternateLinks

The middleware automatically sets the link header to inform search engines that your content is available in different languages. Note that this automatically integrates with your routing strategy and will generate the correct links based on your configuration.

However, there are cases where you may want to provide these links yourself:

1. You have pages that are only available for certain locales
2. You’re using an external system like a CMS to manage localized slugs of your pages

In this case, you can opt-out of this behavior by setting alternateLinks to false.

import {defineRouting} from 'next-intl/routing';
 
export const routing = defineRouting({
  // ...
 
  alternateLinks: false
});

If you decide to manage alternate links yourself, a good option can be to include them in a sitemap.

link: <https://example.com/en>; rel="alternate"; hreflang="en",
      <https://example.com/de>; rel="alternate"; hreflang="de",
      <https://example.com/>; rel="alternate"; hreflang="x-default"

import createMiddleware from 'next-intl/middleware';
import LinkHeader from 'http-link-header';
import {NextRequest} from 'next/server';
import {routing} from './i18n/routing';
 
const handleI18nRouting = createMiddleware(routing);
 
export default async function middleware(request: NextRequest) {
  const response = handleI18nRouting(request);
 
  // Example: Remove the `x-default` entry
  const link = LinkHeader.parse(response.headers.get('link'));
  link.refs = link.refs.filter((entry) => entry.hreflang !== 'x-default');
  response.headers.set('link', link.toString());
 
  return response;
}

next.config.ts

Apart from your routing configuration, next-intl will also incorporate settings from next.config.ts.

basePath

The next-intl middleware as well as the navigation APIs will automatically pick up a basePath that you might have configured in your next.config.js.

Note however that you should make sure that your middleware matcher handles the root of your base path:

export const config = {
  // The `matcher` is relative to the `basePath`
  matcher: [
    // This entry handles the root of the base
    // path and should always be included
    '/'
 
    // ... other matcher config
  ]
};

trailingSlash

If you have trailingSlash set to true in your Next.js config, this setting will be taken into account by the middleware and the navigation APIs.

Note that if you’re using pathnames, your internal and external pathnames can be defined either with or without a trailing slash as they will be normalized internally.