next-intl Documentation

Provide a locale Copy Section

If your app doesn't require unique pathnames per locale, you can provide a locale to next-intl based on user preferences or other application logic.

The simplest option is to use a cookie:

import {cookies} from 'next/headers';
import {getRequestConfig} from 'next-intl/server';

export default getRequestConfig(async () => {
  const store = await cookies();
  const locale = store.get('locale')?.value || 'en';

  return {
    locale
    // ...
  };
});

Internationalization isn't just translating words Copy Section

next-intl provides the essential foundation for internationalization in Next.js apps. It handles aspects like translations, date and number formatting, as well as internationalized routing.

However, building for a global audience spans a wider range of topics:

• Choosing the right architecture and routing strategy for your app

• Integrating with backend services or a CMS

• Leveraging generative AI for content localization

• Streamlining your development workflow with TypeScript and IDE tooling

• Collaborating with your team using a translation management system

• Understanding all the pieces that contribute to a truly localized experience

• Mastering SEO for multilingual apps to reach global audiences

File: docs/src/pages/docs/getting-started/pages-router.mdx Copy Chapter

import {Tabs} from 'nextra/components';
import Callout from '@/components/Callout';

Next.js Pages Router internationalization (i18n)

While it's recommended to use next-intl with the App Router, the Pages Router is still fully supported.

<Tabs items={['Multiple languages', 'Single language']}>
<Tabs.Tab>

1. npm install next-intl
2. Set up internationalized routing
3. Add the provider in _app.tsx

import {NextIntlClientProvider} from 'next-intl';
import {useRouter} from 'next/router';

export default function App({Component, pageProps}) {
  const router = useRouter();

  return (
    <NextIntlClientProvider
      locale={router.locale}
      timeZone="Europe/Vienna"
      messages={pageProps.messages}
    >
      <Component {...pageProps} />
    </NextIntlClientProvider>
  );
}

4. Provide messages on a page-level

export async function getStaticProps(context) {
  return {
    props: {
      // You can get the messages from anywhere you like. The recommended
      // pattern is to put them in JSON files separated by locale and read
      // the desired one based on the `locale` received from Next.js.
      messages: (await import(`../../messages/${context.locale}.json`)).default
    }
  };
}

5. Use translations in your components!

</Tabs.Tab>
<Tabs.Tab>
Even if you only support a single language, next-intl can still be helpful to separate your labels and formatting concerns from your application logic.

1. npm install next-intl

2. Add the provider in _app.tsx

import {NextIntlClientProvider} from 'next-intl';

export default function App({Component, pageProps}) {
  return (
    <NextIntlClientProvider
      locale="en"
      timeZone="Europe/Vienna"
      messages={pageProps.messages}
    >
      <Component {...pageProps} />
    </NextIntlClientProvider>
  );
}

3. Provide messages on a page-level

export async function getStaticProps() {
  const locale = 'en';

  return {
    props: {
      // You can get the messages from anywhere you like. The recommended pattern
      // is to put them in JSON files separated by locale (e.g. `en.json`).
      messages: (await import(`../../messages/${locale}.json`)).default
    }
  };
}

4. Use translations in your components!

</Tabs.Tab>

File: docs/src/pages/docs/routing/configuration.mdx Copy Chapter

import Details from '@/components/Details';
import Card from '@/components/Card';
import Cards from '@/components/Cards';
import Callout from '@/components/Callout';
import {CourseVideoBanner} from '@/components/CourseBanner';

Routing configuration

`defineRouting` Copy Chapter

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.

What if the locales aren't known at build time?

In case you're building an app where locales can be added and removed at runtime, you can provide the routing configuration for the middleware dynamically per request.

To create the corresponding navigation APIs, you can omit the locales argument from createNavigation in this case.

Still, in case you're defining other routing config, make sure to keep them in sync between the middleware and the navigation APIs.

`localePrefix` Copy Section

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) [#locale-prefix-always]

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'` [#locale-prefix-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 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'` [#locale-prefix-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 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` [#locale-prefix-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 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.

Can I read the matched prefix in my app?

Since the custom prefix is rewritten to the locale internally, you can't access the prefix directly. However, you can extract details like the region from the locale:

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

The region must be a valid ISO 3166-1 alpha-2 country code or a UN M49 region code. When passed to Intl.Locale, the region code is treated as case-insensitive and normalized to uppercase. You can also combine languages with regions where the language is not natively spoken (e.g. en-AT describes English as used in Austria).

Apart from the region, a locale can encode further properties, like the numbering system.

If you'd like to encode custom information in the locale, you can use arbitrary private extensions, denoted by the -x- prefix (e.g. en-US-x-usd). The Intl.Locale constructor ignores private extensions, but you can extract them from the locale string manually.

`pathnames` [#pathnames] Copy Section

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.

How can I localize CMS-driven URLs?

If you have a route like /news/[articleSlug], you may want to localize your pathnames like this:

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

In this case, you can use pathnames to localize the static part of the pathname:

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

… and use a localized slug from your CMS for the dynamic part.

When doing this, make sure your locale switcher and alternate links are also aware of your CMS-driven URLs so they point to the correct localized pathnames.

Learn more:

How can I revalidate localized pathnames?

Depending on if a route is generated statically (at build time) or dynamically (at runtime), revalidatePath needs to be called either for the localized or the internal pathname.

Consider this example:

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

… with this routing configuration:

import {defineRouting} from 'next-intl/routing';

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

Depending on whether some-article was included in generateStaticParams or not, you can revalidate the route like this:

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

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

When in doubt, you can revalidate with revalidateTag instead.

See also: vercel/next.js#59825

`domains` Copy Section

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).

Optionally, each domain can override the overall localePrefix setting:

import {defineRouting} from 'next-intl/routing';

export const routing = defineRouting({
  locales: ['en-US', 'en-CA', 'fr-CA', 'fr-FR'],
  defaultLocale: 'en-US',
  localePrefix: 'as-needed',
  domains: [
    {
      domain: 'us.example.com',
      defaultLocale: 'en-US',
      locales: ['en-US'],
      localePrefix: 'never'
    },
    {
      domain: 'ca.example.com',
      defaultLocale: 'en-CA',
      locales: ['en-CA', 'fr-CA'],
      localePrefix: 'always'
    },
    {
      domain: 'fr.example.com',
      defaultLocale: 'fr-FR',
      locales: ['fr-FR']
      // Uses the global setting
    }
  ]
});

See also: Domain-based routing

`localeDetection` [#locale-detection] Copy Section

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.

If you don't rely on a locale cookie being set, you can consider turning it off.

`localeCookie` [#locale-cookie] Copy Section

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

Which maxAge value should I consider for GDPR compliance?

To be compliant out of the box, next-intl does not set the max-age value of the cookie, making it a session cookie that expires when a browser is closed.

Please note that legal requirements may vary by region, so it's advisable to verify them independently. While we strive to keep this information as up-to-date as possible, we cannot guarantee its accuracy.

Learn more:

`alternateLinks` (`hreflang`) [#alternate-links] Copy Section

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

If you want to provide alternate links yourself, you can do so for example with a sitemap or by using the Metadata API.

Learn more:

Which alternate links are included?

Using the middleware defaults, the link header of a response for / will look like this:

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"

The x-default entry is included to point to a variant that can be used if no other language matches the user's browser setting. This special entry is reserved for language selection & detection, in our case issuing a 307 redirect to the best matching locale.

To provide fully specified URLs, the domain is read from the x-forwarded-host header, with a fallback to host (hosting platforms typically provide these headers out of the box).

Your middleware configuration, including options like domains, pathnames and basePath, is automatically incorporated.

Can I customize the alternate links?

If you need to customize the alternate links, you can either turn them off and provide your own implementation, or if you only need to make minor adaptions, you can compose the middleware and add your custom logic after the middleware has run:

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` [#next-config] Copy Chapter

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

`basePath` Copy Section

The middleware as well as the navigation APIs will automatically consider a basePath that you might have configured in your Next.js config.

The only exception is the getPathname function, which will return the bare pathname without a base path. Due to this, you can prefix the returned pathname manually if you need to.

When using a base path, you should make sure that your matcher handles an explicit root:

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` Copy Section

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.

File: docs/src/pages/docs/routing/middleware.mdx Copy Chapter

import Callout from '@/components/Callout';
import Details from '@/components/Details';
import {CourseVideoBanner} from '@/components/CourseBanner';

Proxy / middleware

The next-intl middleware can be created via createMiddleware.

It receives a routing configuration and takes care of:

1. Locale negotiation
2. Applying relevant redirects & rewrites
3. Providing alternate links for search engines

Example:

import createMiddleware from 'next-intl/middleware';
import {routing} from './i18n/routing';

export default createMiddleware(routing);

export const config = {
  // Match all pathnames except for
  // - … if they start with `/api`, `/trpc`, `/_next` or `/_vercel`
  // - … the ones containing a dot (e.g. `favicon.ico`)
  matcher: '/((?!api|trpc|_next|_vercel|.*\\..*).*)'
};

Note: proxy.ts was called middleware.ts up until Next.js 16.

Locale detection [#locale-detection] Copy Chapter

The locale is negotiated based on your routing configuration, taking into account your settings for localePrefix, domains, localeDetection, and localeCookie.

Prefix-based routing (default) [#location-detection-prefix] Copy Section

Prefer to watch a video?

By default, prefix-based routing is used to determine the locale of a request.

In this case, the locale is detected based on these priorities:

1. A locale prefix is present in the pathname (e.g. /en/about)
2. A cookie is present that contains a previously detected locale
3. A locale can be matched based on the accept-language header
4. As a last resort, the defaultLocale is used

To change the locale, users can visit a prefixed route. This will take precedence over a previously matched locale that is saved in a cookie or the accept-language header and will update a previous cookie value.

Example workflow:

1. A user requests / and based on the accept-language header, the en locale is matched.
2. The user is redirected to /en.
3. The app renders <Link locale="de" href="/">Switch to German</Link> to allow the user to change the locale to de.
4. When the user clicks on the link, a request to /de is initiated.
5. The middleware will add a cookie to remember the preference for the de locale.
6. The user later requests / again and the middleware will redirect to /de based on the cookie.

Which algorithm is used to match the accept-language header against the available locales?

To determine the best-matching locale based on the available options from your app, the middleware uses the "best fit" algorithm of @formatjs/intl-localematcher. This algorithm is expected to provide better results than the more conservative "lookup" algorithm that is specified in RFC 4647.

To illustrate this with an example, let's consider your app supports these locales:

1. en-US
2. de-DE

The "lookup" algorithm works by progressively removing subtags from the user's accept-language header until a match is found. This means that if the user's browser sends the accept-language header en-GB, the "lookup" algorithm will not find a match, resulting in the default locale being used.

In contrast, the "best fit" algorithm compares a distance between the user's accept-language header and the available locales, while taking into consideration regional information. Due to this, the "best fit" algorithm is able to match en-US as the best-matching locale in this case.

Domain-based routing [#location-detection-domain] Copy Section

Prefer to watch a video?

If you're using the domains setting, the middleware will match the request against the available domains to determine the best-matching locale. To retrieve the domain, the host is read from the x-forwarded-host header, with a fallback to host (hosting platforms typically provide these headers out of the box).

The locale is detected based on these priorities:

1. A locale prefix is present in the pathname (e.g. ca.example.com/fr)
2. A locale is stored in a cookie and is supported on the domain
3. A locale that the domain supports is matched based on the accept-language header
4. As a fallback, the defaultLocale of the domain is used

Since the middleware is aware of all your domains, if a domain receives a request for a locale that is not supported (e.g. en.example.com/fr), it will redirect to an alternative domain that does support the locale.

Example workflow:

1. The user requests us.example.com and based on the defaultLocale of this domain, the en locale is matched.
2. The app renders <Link locale="fr" href="/">Switch to French</Link> to allow the user to change the locale to fr.
3. When the link is clicked, a request to us.example.com/fr is initiated.
4. The middleware recognizes that the user wants to switch to another domain and responds with a redirect to ca.example.com/fr.

Matcher config Copy Chapter

The middleware is intended to only run on pages, not on arbitrary files that you serve independently of the user locale (e.g. /favicon.ico).

A popular strategy is to match all routes that don't start with certain segments (e.g. /_next) and also none that include a dot (.) since these typically indicate static files. However, if you have some routes where a dot is expected (e.g. /users/jane.doe), you should explicitly provide a matcher for these.

export const config = {
  // Matcher entries are linked with a logical "or", therefore
  // if one of them matches, the middleware will be invoked.
  matcher: [
    // Match all pathnames except for
    // - … if they start with `/api`, `/_next` or `/_vercel`
    // - … the ones containing a dot (e.g. `favicon.ico`)
    '/((?!api|_next|_vercel|.*\\..*).*)',

    // However, match all pathnames within `/users`, optionally with a locale prefix
    '/([\\w-]+)?/users/(.+)'
  ]
};

{/* Keep this in sync with packages/next-intl/test/middleware/middleware.test.tsx */}

Note that some third-party providers like Vercel Analytics typically use internal endpoints that are then rewritten to an external URL (e.g. /_vercel/insights/view). Make sure to exclude such requests from your middleware matcher so they aren't rewritten by accident.

Composing other middlewares Copy Chapter

By calling createMiddleware, you'll receive a function of the following type:

function middleware(request: NextRequest): NextResponse;

If you need to incorporate additional behavior, you can either modify the request before the next-intl middleware receives it, modify the response or even create the middleware based on dynamic configuration.

import createMiddleware from 'next-intl/middleware';
import {NextRequest} from 'next/server';

export default async function proxy(request: NextRequest) {
  // Step 1: Use the incoming request (example)
  const defaultLocale = request.headers.get('x-your-custom-locale') || 'en';

  // Step 2: Create and call the next-intl middleware (example)
  const handleI18nRouting = createMiddleware({
    locales: ['en', 'de'],
    defaultLocale
  });
  const response = handleI18nRouting(request);

  // Step 3: Alter the response (example)
  response.headers.set('x-your-custom-locale', defaultLocale);

  return response;
}

export const config = {
  // Match only internationalized pathnames
  matcher: '/((?!api|trpc|_next|_vercel|.*\\..*).*)'
};

Example: Additional rewrites Copy Section

If you need to handle rewrites apart from the ones provided by next-intl, you can call NextResponse.rewrite() conditionally after the next-intl middleware has run.

This example rewrites requests for /[locale]/profile to /[locale]/profile/new if a special cookie is set.

import createMiddleware from 'next-intl/middleware';
import {NextRequest, NextResponse} from 'next/server';
import {routing} from './i18n/routing';

const handleI18nRouting = createMiddleware(routing);

export default async function proxy(request: NextRequest) {
  let response = handleI18nRouting(request);

  // Additional rewrite when NEW_PROFILE cookie is set
  if (response.ok) {
    // (not for errors or redirects)
    const [, locale, ...rest] = new URL(
      response.headers.get('x-middleware-rewrite') || request.url
    ).pathname.split('/');
    const pathname = '/' + rest.join('/');

    if (
      pathname === '/profile' &&
      request.cookies.get('NEW_PROFILE')?.value === 'true'
    ) {
      response = NextResponse.rewrite(
        new URL(`/${locale}/profile/new`, request.url),
        {headers: response.headers}
      );
    }
  }

  return response;
}

export const config = {
  // Match only internationalized pathnames
  matcher: '/((?!api|trpc|_next|_vercel|.*\\..*).*)'
};

You may wish to customize this based on your routing configuration and use case.

Starter templates (auth, saas, tenants) Copy Section

🌐 learn.next-intl.dev provides additional starter templates with middleware composition.

Including:

• app-router-auth with Better Auth: Auth-protected app with locale from user settings.
• app-router-saas with Better Auth: Locale prefixes on public routes with a login to a protected app.
• app-router-tenants: An advanced composition pattern that routes between multiple tenants and a landing page while supporting multiple locales.

Source code

Usage without proxy / middleware (static export) Copy Chapter

If you're using the static export feature from Next.js (output: 'export'), a proxy / middleware will not run. You can use prefix-based routing nonetheless to internationalize your app, but a few tradeoffs apply.

Static export limitations:

1. Using a locale prefix is required (same as localePrefix: 'always')
2. The locale can't be negotiated on the server (same as localeDetection: false)
3. You can't use pathnames, as these require server-side rewrites
4. Static rendering is required

Additionally, other limitations as documented by Next.js will apply too.

If you choose this approach, you might want to enable a redirect at the root of your app:

import {redirect} from 'next/navigation';

// Redirect the user to the default locale when `/` is requested
export default function RootPage() {
  redirect('/en');
}

If you add such a root page at app/page.tsx, you need to add a root layout at app/layout.tsx as well, even if it's just passing children through:

export default function RootLayout({children}) {
  return children;
}

Troubleshooting Copy Chapter

"The proxy / middleware doesn't run for a particular page." [#middleware-not-running] Copy Section

To resolve this, make sure that:

1. The proxy / middleware is set up in the correct file (e.g. src/proxy.ts).
2. Your matcher correctly matches all routes of your application, including dynamic segments with potentially unexpected characters like dots (e.g. /users/jane.doe).
3. In case you're composing other middlewares, ensure that the middleware is called correctly.
4. In case you require static rendering, make sure to follow the static rendering guide instead of relying on hacks like force-static.

"My page content isn't localized despite the pathname containing a locale prefix." [#content-not-localized] Copy Section

This is very likely the result of your proxy / middleware not running on the request. As a result, a potential fallback from i18n/request.ts might be applied.

"Unable to find `next-intl` locale because the proxy / middleware didn't run on this request and no `locale` was returned in `getRequestConfig`." [#unable-to-find-locale] Copy Section

If the middleware is not expected to run on this request (e.g. because you're using a setup without locale-based routing, you should explicitly return a locale from getRequestConfig to recover from this error.

If the middleware is expected to run, verify that your middleware is set up correctly.

Note that next-intl will invoke the notFound() function to abort the render if no locale is available after getRequestConfig has run. You should consider adding a not-found page due to this.

File: docs/src/pages/docs/routing/navigation.mdx Copy Chapter

import Callout from '@/components/Callout';
import Details from '@/components/Details';
import {CourseVideoBanner} from '@/components/CourseBanner';

Navigation APIs

Prefer to watch a video?

next-intl provides lightweight wrappers around Next.js' navigation APIs like <Link /> and useRouter that automatically handle the user locale and pathnames behind the scenes.

To create these APIs, you can call the createNavigation function with your routing configuration:

import {createNavigation} from 'next-intl/navigation';
import {routing} from './routing';

export const {Link, redirect, usePathname, useRouter, getPathname} =
  createNavigation(routing);

This function is typically called in a central module like src/i18n/navigation.ts in order to provide easy access to navigation APIs in your components.

What if the locales aren't known at build time?

In case you're building an app where locales can be added and removed at runtime, createNavigation can be called without the locales argument, therefore allowing any string that is encountered at runtime to be a valid locale. In this case, you'd not use the defineRouting function.

import {createNavigation} from 'next-intl/navigation';

export const {Link, redirect, usePathname, useRouter, getPathname} =
  createNavigation({
    // ... potentially other routing
    // config, but no `locales` ...
  });

Note however that the locales argument for the middleware is still mandatory. If you need to fetch the available locales at runtime, you can provide the routing configuration for the middleware dynamically per request.

APIs Copy Chapter

The created navigation APIs are thin wrappers around the equivalents from Next.js and mostly adhere to the same function signatures. Your routing configuration and the user's locale are automatically incorporated.

If you're using the pathnames setting in your routing configuration, the internal pathnames that are accepted for href arguments will be strictly typed and localized to the given locale.

`Link` Copy Section

This component wraps next/link and localizes the pathname as necessary.

import {Link} from '@/i18n/navigation';

// When the user is on `/en`, the link will point to `/en/about`
<Link href="/about">About</Link>

// Search params can be added via `query`
<Link href={{pathname: "/users", query: {sortBy: 'name'}}}>Users</Link>

// You can override the `locale` to switch to another language
// (this will set the `hreflang` attribute on the anchor tag)
<Link href="/" locale="de">Switch to German</Link>

Depending on if you're using the pathnames setting, dynamic params can either be passed as:

// 1. A final string (when not using `pathnames`)
<Link href="/users/12">Susan</Link>

// 2. An object (when using `pathnames`)
<Link href={{
  pathname: '/users/[userId]',
  params: {userId: '5'}
}}>
  Susan
</Link>

How can I render a navigation link?

The useSelectedLayoutSegment hook from Next.js allows you to detect if a given child segment is active from within the parent layout. Since this returns an internal pathname, it can be matched against an href that you can pass to Link.

'use client';

import {useSelectedLayoutSegment} from 'next/navigation';
import {ComponentProps} from 'react';
import {Link} from '@/i18n/navigation';

export default function NavigationLink({
  href,
  ...rest
}: ComponentProps<typeof Link>) {
  const selectedLayoutSegment = useSelectedLayoutSegment();
  const pathname = selectedLayoutSegment ? `/${selectedLayoutSegment}` : '/';
  const isActive = pathname === href;

  return (
    <Link
      aria-current={isActive ? 'page' : undefined}
      href={href}
      style={{fontWeight: isActive ? 'bold' : 'normal'}}
      {...rest}
    />
  );
}

<nav>
  <NavigationLink href="/">{t('home')}</NavigationLink>
  <NavigationLink href="/about">{t('about')}</NavigationLink>
  <NavigationLink href="/blog">{t('blog')}</NavigationLink>
</nav>

See also the Next.js docs on creating an active link component.

How can I compose the link with its href prop?

If you need to create a component that receives an href prop that is forwarded to Link internally, you can compose the props from Link with the ComponentProps type:

import {ComponentProps} from 'react';
import {Link} from '@/i18n/navigation';

type Props = ComponentProps<typeof Link> & {
  color: 'blue' | 'red';
};

export default function StyledLink({color, href, ...rest}: Props) {
  return <Link href={href} style={{color}} {...rest} />;
}

In case you're using the pathnames setting, the href prop of the wrapping component will now be strictly typed based on your routing configuration.

Why does <Link /> always set a locale prefix when using the locale prop?

If you're providing a locale prop, typically to change the locale of the target page, you might notice that the link's href will always include a locale prefix, even if you're using a localePrefix setting other than always.

Example:

If you're using localePrefix: 'as-needed' and en is your default locale, then the href for this link will still be /en/about:

// Links to `/en/about`
<Link href="/about" locale="en">
  About
</Link>

The reason for this is that a potential cookie may need to be updated before the user can visit the unprefixed route at /about. The prefixed pathname will take care of this and will subsequently redirect to the unprefixed route. This behavior is necessary because links might be interacted with before your page is hydrated and client-side code would have a chance to update the cookie.

If you'd like to avoid this behavior, you can instead use useRouter to switch the locale, which can rely on updating the cookie on the client side before navigating to the target page.

How can I link to unknown routes when using the pathnames setting?

In this case, the navigation APIs are strictly typed and only allow routes specified in the pathnames config. If you need to link to unknown routes in certain places, you can disable the type checking on a case-by-case basis:

// @ts-expect-error
<Link href="/unknown">...</Link>

Unknown routes will be passed through as-is, but will receive relevant locale prefixes in case of absolute pathnames.

How does prefetching of localized links work?

<Link /> from next-intl inherits the default prefetch behavior from next/link.

The one exception to this is when you've set the locale prop. In this case, the link will not be prefetched, because this would otherwise result in prematurely overwriting the locale cookie as part of the prefetch request.

`useRouter` Copy Section

If you need to navigate programmatically, e.g. in an event handler, next-intl provides a convience API that wraps useRouter from Next.js and localizes the pathname accordingly.

'use client';

import {useRouter} from '@/i18n/navigation';

const router = useRouter();

// When the user is on `/en`, the router will navigate to `/en/about`
router.push('/about');

// Search params can be added via `query`
router.push({
  pathname: '/users',
  query: {sortBy: 'name'}
});

// You can override the `locale` to switch to another language
router.replace('/about', {locale: 'de'});

Depending on if you're using the pathnames setting, dynamic params can either be passed as:

// 1. A final string (when not using `pathnames`)
router.push('/users/12');

// 2. An object (when using `pathnames`)
router.push({
  pathname: '/users/[userId]',
  params: {userId: '5'}
});

How can I change the locale for the current page?

By combining usePathname with useRouter, you can change the locale for the current page programmatically by navigating to the same pathname, while overriding the locale.

Depending on if you're using the pathnames setting, you optionally have to forward params to potentially resolve an internal pathname.

'use client';

import {usePathname, useRouter} from '@/i18n/navigation';
import {useParams} from 'next/navigation';

const pathname = usePathname();
const router = useRouter();

// Without `pathnames`: Pass the current `pathname`
router.replace(pathname, {locale: 'de'});

// With `pathnames`: Pass `params` as well
const params = useParams();
router.replace(
  // @ts-expect-error -- TypeScript will validate that only known `params`
  // are used in combination with a given `pathname`. Since the two will
  // always match for the current route, we can skip runtime checks.
  {pathname, params},
  {locale: 'de'}
);

Learn more:

`usePathname` Copy Section

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

'use client';

import {usePathname} from '@/i18n/navigation';

// When the user is on `/en`, this will be `/`
const pathname = usePathname();

Note that if you're using the pathnames setting, the returned pathname will correspond to an internal pathname template (dynamic params will not be replaced by their values).

// When the user is on `/de/über-uns`, this will be `/about`
const pathname = usePathname();

// When the user is on `/de/neuigkeiten/produktneuheit`,
// this will be `/news/[articleSlug]`
const pathname = usePathname();

`redirect` Copy Section

If you want to interrupt the render and redirect to another page, you can invoke the redirect function. This wraps redirect from Next.js and localizes the pathname as necessary.

Note that a locale prop is always required, even if you're just passing the current locale.

import {redirect} from '@/i18n/navigation';

// Redirects to `/en/login`
redirect({href: '/login', locale: 'en'});

// Search params can be added via `query`
redirect({href: '/users', query: {sortBy: 'name'}, locale: 'en'});

Depending on if you're using the pathnames setting, dynamic params can either be passed as:

// 1. A final string (when not using `pathnames`)
redirect({href: '/users/12', locale: 'en'});

// 2. An object (when using `pathnames`)
redirect({
  href: {
    pathname: '/users/[userId]',
    params: {userId: '5'}
  },
  locale: 'en'
});

When using a localePrefix setting other than always, you can enforce a locale prefix by setting the forcePrefix option to true. This is useful when changing the user's locale and you need to update the locale cookie first:

// Will initially redirect to `/en/about` to update the locale
// cookie, regardless of your `localePrefix` setting
redirect({href: '/about', locale: 'en', forcePrefix: true});

Why does TypeScript not narrow types correctly after calling redirect?

TypeScript currently has a limitation with control flow analysis, which results in not being able to narrow types correctly after calling redirect as well as detecting unreachable code:

import {redirect} from '@/i18n/navigation';

function UserProfile({userId}: {userId?: string}) {
  if (!userId) {
    redirect({href: '/login', locale: 'en'});
  }

  // `userId` should be narrowed to `string` here,
  // but TypeScript doesn't analyze this correctly
}

To work around this limitation, you can return the call to the redirect function:

if (!userId) {
  return redirect({href: '/login', locale: 'en'});
}

// ✅ `userId` is narrowed to `string` here

`getPathname` Copy Section

If you need to construct a particular pathname based on a locale, you can call the getPathname function.

import {getPathname} from '@/i18n/navigation';

// Will return `/en/about`
const pathname = getPathname({
  locale: 'en',
  href: '/about'
});

// Search params can be added via `query`
const pathname = getPathname({
  locale: 'en',
  href: {
    pathname: '/users',
    query: {sortBy: 'name'}
  }
});

Depending on if you're using the pathnames setting, dynamic params can either be passed as:

// 1. A final string (when not using `pathnames`)
const pathname = getPathname({
  locale: 'en',
  href: '/users/12'
});

// 2. An object (when using `pathnames`)
const pathname = getPathname({
  locale: 'en',
  href: {
    pathname: '/users/[userId]',
    params: {userId: '5'}
  }
});

Use cases:

File: docs/src/pages/docs/routing/setup.mdx Copy Chapter

import {Tabs} from 'nextra/components';
import Callout from '@/components/Callout';
import Steps from '@/components/Steps';
import Details from '@/components/Details';
import {CourseVideoBanner} from '@/components/CourseBanner';

Setup locale-based routing

Prefer to watch a video?

In order to use unique pathnames for every language that your app supports, next-intl can be used to handle the following routing setups:

1. Prefix-based routing (e.g. /en/about)
2. Domain-based routing (e.g. en.example.com/about)

In either case, next-intl integrates with the App Router by using a top-level [locale] dynamic segment that can be used to provide content in different languages.

Initial setup Copy Chapter

To get started with locale-based routing, we'll set up the following files:

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

import createMiddleware from 'next-intl/middleware';
import {routing} from './i18n/routing';

export default createMiddleware(routing);

export const config = {
  // Match all pathnames except for
  // - … if they start with `/api`, `/trpc`, `/_next` or `/_vercel`
  // - … the ones containing a dot (e.g. `favicon.ico`)
  matcher: '/((?!api|trpc|_next|_vercel|.*\\..*).*)'
};

// ...

export const config = {
  matcher: [
    // Match all pathnames except for
    // - … if they start with `/api`, `/trpc`, `/_next` or `/_vercel`
    // - … the ones containing a dot (e.g. `favicon.ico`)
    '/((?!api|trpc|_next|_vercel|.*\\..*).*)',

    // Match all pathnames within `{/:locale}/users`
    '/([\\w-]+)?/users/(.+)'
  ]
};

import {createNavigation} from 'next-intl/navigation';
import {routing} from './routing';

// Lightweight wrappers around Next.js' navigation
// APIs that consider the routing configuration
export const {Link, redirect, usePathname, useRouter, getPathname} =
  createNavigation(routing);

import * as rootParams from 'next/root-params';
import {notFound} from 'next/navigation';
import {getRequestConfig} from 'next-intl/server';
import {hasLocale} from 'next-intl';
import {routing} from './routing';

export default getRequestConfig(async ({locale}) => {
  if (!locale) {
    const paramValue = await rootParams.locale();
    if (hasLocale(routing.locales, paramValue)) {
      locale = paramValue;
    } else {
      notFound();
    }
  }

  return {
    locale
    // ...
  };
});

src
└── app
    └── [locale]
        ├── layout.tsx
        ├── page.tsx
        └── ...

That's all it takes!

The locale that was matched is now correctly incorporated in all functionality from next-intl:

import {useTranslations} from 'next-intl';

export default function Page() {
  // ✅ Uses the locale from `i18n/request.ts`
  const t = useTranslations();

  // ...
}

From here, you can configure your routing to cater to your specific needs.

In case you ran into an issue, have a look at the App Router example to explore a working app.

Static rendering Copy Chapter

With `next/root-params` Copy Section

When you follow the setup instructions with next/root-params above, your app is automatically eligible for static rendering. Since we are using a dynamic route segment for the [locale] param, we need to use generateStaticParams so that the routes can be rendered at build time.

Depending on your needs, you can add generateStaticParams either to a layout or pages:

1. Layout: Enables static rendering for all pages within this layout (e.g. app/[locale]/layout.tsx)
2. Individual pages: Enables static rendering for a specific page (e.g. app/[locale]/page.tsx)

Example:

import {routing} from '@/i18n/routing';

export function generateStaticParams() {
  return routing.locales.map((locale) => ({locale}));
}

Do I need to return all locales from generateStaticParams?

If you prefer to only render certain locales at build time, or none at all, you can be selective about the ones you return from generateStaticParams (see Static Rendering in the Next.js docs).

With `setRequestLocale` (legacy) Copy Section

When using locale-based routing, next-intl will currently opt into dynamic rendering when APIs like useTranslations are used in Server Components. This is a limitation that we aim to remove in the future, but as a stopgap solution, next-intl provides a temporary API that can be used to enable static rendering.

import {routing} from '@/i18n/routing';

export function generateStaticParams() {
  return routing.locales.map((locale) => ({locale}));
}

import {setRequestLocale} from 'next-intl/server';
import {hasLocale} from 'next-intl';
import {notFound} from 'next/navigation';
import {routing} from '@/i18n/routing';

type Props = {
  children: React.ReactNode;
  params: Promise<{locale: string}>;
};

export default async function LocaleLayout({children, params}: Props) {
  const {locale} = await params;
  if (!hasLocale(routing.locales, locale)) {
    notFound();
  }

  // Enable static rendering
  setRequestLocale(locale);

  return (
    // ...
  );
}

import {use} from 'react';
import {setRequestLocale} from 'next-intl/server';
import {useTranslations} from 'next-intl';

export default function IndexPage({params}) {
  const {locale} = use(params);

  // Enable static rendering
  setRequestLocale(locale);

  // Once the request locale is set, you
  // can call hooks from `next-intl`
  const t = useTranslations('IndexPage');

  return (
    // ...
  );
}

import {getTranslations} from 'next-intl/server';

export async function generateMetadata({params}) {
  const {locale} = await params;
  const t = await getTranslations({locale, namespace: 'Metadata'});

  return {
    title: t('title')
  };
}