# General Translation React SDKs (gt-react, gt-next): createNextMiddleware
URL: https://generaltranslation.com/en-GB/docs/react/nextjs/reference/functions/create-next-middleware.mdx
---

title: createNextMiddleware
description: Add locale routing and detection to a Next.js app with General Translation. API reference for createNextMiddleware.

---

The `createNextMiddleware` function from `gt-next/middleware` adds locale-based routing and detection to a Next.js app. It detects each visitor's locale, stores it in a cookie, and routes them to the localised version of a page.

Use the [App Router middleware guide](/docs/react/nextjs/app-router-middleware) or [Pages Router middleware guide](/docs/react/nextjs/pages-router-middleware) for router-specific setup.

## Overview [#overview]

Create the middleware and export it, along with a path matcher, from your middleware file. Place it in your project root — `proxy.ts` on Next.js 16+, or `middleware.ts` on Next.js 15 and below — not inside `app/` or `pages/`.

```ts title="proxy.ts"
import { createNextMiddleware } from 'gt-next/middleware';

export default createNextMiddleware();

export const config = {
  // Match all paths except API routes, static files, and Next.js internals
  matcher: ['/((?!api|static|.*\\..*|_next).*)'],
};
```

## How it works [#how-it-works]

The middleware resolves each request's locale from these sources, in order:

1. **URL locale** — a locale prefix in the pathname, such as `/es/about`.
2. **Cookie** — the visitor's previously selected locale.
3. **Browser headers** — the `Accept-Language` header.
4. **Default locale** — your configured `defaultLocale` as the fallback.

It then sets a locale cookie and, when `localeRouting` is enabled, redirects or rewrites to the correct localised path. By default, the `defaultLocale` is not prefixed (`/about` stays `/about`), while other locales are (`/es/about`). Locale codes are standardised to canonical form when General Translation services are enabled, and unsupported locales produce a build-time warning.

## Options [#options]

`createNextMiddleware` takes a single options object. All fields are optional.

| Option                                          | Description                               | Type      | Optional | Default |
| ----------------------------------------------- | ----------------------------------------- | --------- | -------- | ------- |
| [`localeRouting`](#locale-routing)              | Enable locale-based routing.              | `boolean` | Yes      | `true`  |
| [`prefixDefaultLocale`](#prefix-default-locale) | Prefix the default locale in the URL too. | `boolean` | Yes      | `false` |
| [`ignoreSourceMaps`](#ignore-source-maps)       | Skip Next.js source-map requests.         | `boolean` | Yes      | `true`  |
| [`pathConfig`](#path-config)                    | Localised path overrides.                 | `object`  | Yes      | `{}`    |

*Note: to restrict which pathnames the middleware runs on, set [`pathRegex`](/docs/react/nextjs/config#path-regex) in `withGTConfig` — it is not a middleware option. The `matcher` in your exported `config` is what Next.js uses to decide whether the middleware runs at all.*

### `localeRouting` [#locale-routing]

**Type** `boolean` · **Optional** · **Default** `true`

Enables locale-based routing and redirects. When `false`, the middleware still detects and stores the locale but does not add locale prefixes or rewrite paths.

### `prefixDefaultLocale` [#prefix-default-locale]

**Type** `boolean` · **Optional** · **Default** `false`

When `false` (the default), the default locale is served without a prefix (`/about`), while other locales are prefixed (`/es/about`). When `true`, every locale is prefixed, including the default (`/en/about`).

### `ignoreSourceMaps` [#ignore-source-maps]

**Type** `boolean` · **Optional** · **Default** `true`

When `true`, requests for Next.js source maps are passed through untouched.

### `pathConfig` [#path-config]

**Type** `object` · **Optional** · **Default** `{}`

Maps shared paths to localised paths, so a route can have a different URL for each locale. Each key is the shared path; each value is either a single localised path or a per-locale map. Dynamic segments such as `[id]` are preserved.

```ts title="proxy.ts"
export default createNextMiddleware({
  pathConfig: {
    // English: /products, Chinese: /zh/产品
    '/products': {
      zh: '/产品',
    },
    // Dynamic routes: /product/123, /zh/产品/123
    '/product/[id]': {
      zh: '/产品/[id]',
    },
  },
});
```

## Example [#example]

```ts title="proxy.ts"
import { createNextMiddleware } from 'gt-next/middleware';

export default createNextMiddleware({
  prefixDefaultLocale: true,
  pathConfig: {
    '/about': {
      fr: '/a-propos',
    },
  },
});

export const config = {
  matcher: ['/((?!api|static|.*\\..*|_next).*)'],
};
```

*Warning: test your matcher carefully. An overly broad matcher can cause redirect loops or break static assets.*