Routing configuration

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.

Learn more:

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 not using locale-based routing 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 there’s 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

Prefer to watch a video?

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

Example:

• /en/about
• /de/über-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 locales use different paths, you can
    // specify the relevant external pathnames
    '/services': {
      de: '/leistungen'
    },
 
    // Encoding of non-ASCII characters is handled
    // automatically where relevant
    '/about': {
      de: '/über-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/über-uns will be handled by the page at /[locale]/about/page.tsx.

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

'/news/[articleSlug]': {
  de: '/neuigkeiten/[articleSlug]'
}

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');

domains

Prefer to watch a video?

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 default locale matching based on prefixes (e.g. on localhost, for local development).

See also: Domain-based routing

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 (hreflang)

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 pathnames 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
});

Learn more:

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.