Middleware

The middleware receives a routing configuration and takes care of:

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

import createMiddleware from 'next-intl/middleware';
import {routing} from './i18n/routing';
 
export default createMiddleware(routing);
 
export const config = {
  // Match only internationalized pathnames
  matcher: ['/', '/(de|en)/:path*']
};

Locale detection

The locale is negotiated based on your localePrefix and domains setting. Once a locale is detected, it will be remembered for future requests by being stored in the NEXT_LOCALE cookie.

Prefix-based routing (default)

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 (opens in a new tab)
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 the previous cookie value.

Example workflow:

1. A user requests / and based on the accept-language header, the en locale is matched.
2. The en locale is saved in a cookie and 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 update the cookie value to de.

Domain-based routing

If you're using domain-based routing, 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 (opens in a new tab)
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.

X-Forwarded-Host: example.com

Configuration

Apart from the routing configuration that is shared with the navigation APIs, the middleware accepts a few additional options that can be used for customization.

Turning off locale detection

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 createMiddleware from 'next-intl/middleware';
import {routing} from './i18n/routing';
 
export default createMiddleware(routing, {
  localeDetection: false
});

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

Note that by setting this option, the middleware will no longer return a set-cookie response header, which can be beneficial for CDN caching (see e.g. the Cloudflare Cache rules for set-cookie (opens in a new tab)).

Alternate links

The middleware automatically sets the link header (opens in a new tab) 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 createMiddleware from 'next-intl/middleware';
import {routing} from './i18n/routing';
 
export default createMiddleware(routing, {
  alternateLinks: false // Defaults to `true`
});

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

Matcher config

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

Because of this, the following config is generally recommended:

export const config = {
  // Match only internationalized pathnames
  matcher: ['/', '/(de|en)/:path*']
};

This enables:

1. A redirect at / to a suitable locale
2. Internationalization of all pathnames starting with a locale (e.g. /en/about)

import {NextRequest} from 'next/server';
import createMiddleware from 'next-intl/middleware';
import {routing} from './i18n/routing';
 
const handleI18nRouting = createMiddleware(routing);
 
export default function middleware(request: NextRequest) {
  const {pathname} = request.nextUrl;
 
  const shouldHandle =
    pathname === '/' ||
    new RegExp(`^/(${locales.join('|')})(/.*)?$`).test(
      request.nextUrl.pathname
    );
  if (!shouldHandle) return;
 
  return handleI18nRouting(request);
}

Pathnames without a locale prefix

There are two use cases where you might want to match pathnames without a locale prefix:

1. You're using a config for localePrefix other than always
2. You want to enable redirects that add a locale for unprefixed pathnames (e.g. /about → /en/about)

For these cases, the middleware should run on requests for pathnames without a locale prefix as well.

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/(.+)'
  ]
};

Note that some third-party providers like Vercel Analytics (opens in a new tab) and umami (opens in a new tab) 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.

Base path

The next-intl middleware as well as the navigation APIs will automatically pick up a basePath (opens in a new tab) 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
  ]
};

Trailing slash

If you have trailingSlash (opens in a new tab) set to true in your Next.js config, this setting will be taken into account when the middleware generates pathnames, e.g. for redirects.

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

Composing other middlewares

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 middleware(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: ['/', '/(de|en)/:path*']
};

Example: Additional rewrites

If you need to handle rewrites apart from the ones provided by next-intl, you can adjust the pathname of the request before invoking the next-intl middleware (based on "A/B Testing with Cookies" by Vercel (opens in a new tab)).

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} from 'next/server';
 
export default async function middleware(request: NextRequest) {
  const [, locale, ...segments] = request.nextUrl.pathname.split('/');
 
  if (locale != null && segments.join('/') === 'profile') {
    const usesNewProfile =
      (request.cookies.get('NEW_PROFILE')?.value || 'false') === 'true';
 
    if (usesNewProfile) {
      request.nextUrl.pathname = `/${locale}/profile/new`;
    }
  }
 
  const handleI18nRouting = createMiddleware({
    locales: ['en', 'de'],
    defaultLocale: 'en'
  });
  const response = handleI18nRouting(request);
  return response;
}
 
export const config = {
  matcher: ['/', '/(de|en)/:path*']
};

Note that if you use a localePrefix other than always, you need to adapt the handling appropriately to handle unprefixed pathnames too.

Example: Integrating with Clerk

@clerk/nextjs (opens in a new tab) provides a middleware that can be combined (opens in a new tab) with other middlewares like the one provided by next-intl. By combining them, the middleware from @clerk/next will first ensure protected routes are handled appropriately. Subsequently, the middleware from next-intl will run, potentially redirecting or rewriting incoming requests.

import {clerkMiddleware, createRouteMatcher} from '@clerk/nextjs/server';
import createMiddleware from 'next-intl/middleware';
import {routing} from './i18n/routing';
 
const handleI18nRouting = createMiddleware(routing);
 
const isProtectedRoute = createRouteMatcher(['/:locale/dashboard(.*)']);
 
export default clerkMiddleware((auth, req) => {
  if (isProtectedRoute(req)) auth().protect();
 
  return handleI18nRouting(req);
});
 
export const config = {
  // Match only internationalized pathnames
  matcher: ['/', '/(de|en)/:path*']
};

(based on @clerk/nextjs@^5.0.0)

Example: Integrating with Supabase Authentication

In order to use Supabase Authentication with next-intl, you need to combine the Supabase middleware with the one from next-intl.

You can do so by following the setup guide from Supabase (opens in a new tab) and adapting the middleware utils to accept a response object that's been created by the next-intl middleware instead of creating a new one:

import {createServerClient} from '@supabase/ssr';
import {NextResponse, type NextRequest} from 'next/server';
 
export async function updateSession(
  request: NextRequest,
  response: NextResponse
) {
  const supabase = createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        getAll() {
          return request.cookies.getAll();
        },
        setAll(cookiesToSet) {
          cookiesToSet.forEach(({name, value}) =>
            request.cookies.set(name, value)
          );
          cookiesToSet.forEach(({name, value, options}) =>
            response.cookies.set(name, value, options)
          );
        }
      }
    }
  );
 
  const {
    data: {user}
  } = await supabase.auth.getUser();
 
  return response;
}

Now, we can integrate the Supabase middleware with the one from next-intl:

import createMiddleware from 'next-intl/middleware';
import {type NextRequest} from 'next/server';
import {routing} from './i18n/routing';
import {updateSession} from './utils/supabase/middleware';
 
const handleI18nRouting = createMiddleware(routing);
 
export async function middleware(request: NextRequest) {
  const response = handleI18nRouting(request);
 
  // A `response` can now be passed here
  return await updateSession(request, response);
}
 
export const config = {
  matcher: ['/', '/(de|en)/:path*']
};

(based on @supabase/ssr@^0.5.0)

Example: Integrating with Auth.js (aka NextAuth.js)

The Next.js middleware of Auth.js (opens in a new tab) requires an integration with their control flow to be compatible with other middlewares. The success callback (opens in a new tab) can be used to run the next-intl middleware on authorized pages. However, public pages need to be treated separately.

For pathnames specified in the pages object (opens in a new tab) (e.g. signIn), Auth.js will skip the entire middleware and not run the success callback. Therefore, we have to detect these pages before running the Auth.js middleware and only run the next-intl middleware in this case.

import {withAuth} from 'next-auth/middleware';
import createMiddleware from 'next-intl/middleware';
import {NextRequest} from 'next/server';
import {routing} from './i18n/routing';
 
const publicPages = ['/', '/login'];
 
const handleI18nRouting = createMiddleware(routing);
 
const authMiddleware = withAuth(
  // Note that this callback is only invoked if
  // the `authorized` callback has returned `true`
  // and not for pages listed in `pages`.
  function onSuccess(req) {
    return handleI18nRouting(req);
  },
  {
    callbacks: {
      authorized: ({token}) => token != null
    },
    pages: {
      signIn: '/login'
    }
  }
);
 
export default function middleware(req: NextRequest) {
  const publicPathnameRegex = RegExp(
    `^(/(${locales.join('|')}))?(${publicPages
      .flatMap((p) => (p === '/' ? ['', '/'] : p))
      .join('|')})/?$`,
    'i'
  );
  const isPublicPage = publicPathnameRegex.test(req.nextUrl.pathname);
 
  if (isPublicPage) {
    return handleI18nRouting(req);
  } else {
    return (authMiddleware as any)(req);
  }
}
 
export const config = {
  matcher: ['/((?!api|_next|.*\\..*).*)']
};

(based on next-auth@^4.0.0)

Usage without middleware (static export)

If you're using the static export (opens in a new tab) feature from Next.js (output: 'export'), the middleware will not run. You can use prefix-based routing nontheless 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 at runtime (same as localeDetection: false)
3. You can't use pathname localization
4. Static rendering is required
5. You need to add a redirect for the root of the app

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

Note that other limitations as documented by Next.js (opens in a new tab) will apply too.

Troubleshooting

"Unable to find next-intl locale because the middleware didn't run on this request."

This can happen either because:

1. You're using a setup with i18n routing but the middleware is not set up.
2. You're using a setup without i18n routing but are reading the locale param passed to the function within getRequestConfig or you're not returning a locale.
3. The middleware is set up in the wrong file (e.g. you're using the src folder, but middleware.ts was added in the root folder).
4. The middleware matcher didn't match a request, but you're using APIs from next-intl in server code (e.g. a Server Component, a Server Action, etc.).
5. You're attempting to implement static rendering via force-static (opens in a new tab).

To recover from this error, please make sure that:

1. You're consistently using a setup with or without i18n routing (i.e. with or without the routing APIs).
2. If you're using a setup with i18n routing:
   1. You're using APIs from next-intl (including the navigation APIs) exclusively within the [locale] segment.
   2. Your middleware matcher matches all routes of your application, including dynamic segments with potentially unexpected characters like dots (e.g. /users/jane.doe).
   3. If you're using localePrefix: 'as-needed', the locale segment effectively acts like a catch-all for all unknown routes. You should make sure that the locale is validated before it's used by any APIs from next-intl.
   4. To implement static rendering, make sure to provide a static locale to next-intl instead of using force-static.
3. If you're using using a setup without i18n routing:
   1. You don't read the locale param in getRequestConfig but instead return it.

Note that next-intl will invoke the notFound() function to abort the render if the locale can't be found. You should consider adding a not-found page due to this.