i18n Routing

Overview

This guide will walk you through adding i18n routing and localized paths to your Next.js application using gt-next's built-in middleware.

What is i18n Routing?

Creating new routes for each language has the advantage of making your website more user friendly and improve SEO. i18n routing allows you to associate specific URLs with different locales. For example, you can have /en/airplanes for English, /zh/airplanes for Chinese, and so on.

You can take this one step further with localized paths. These are an extension of i18n routing that allow you to specify an alias path for a locale. For example, you can specify /en/airplanes for English, /zh/飞机 for Chinese, and so on.

Set up i18n routing

We will take you through two easy steps to add i18n routing to your Next.js application:

Step 1: Add a Dynamic Route

Insert a directory in your app folder called [locale] (e.g., app/[locale]). Include all of your pages and layouts under this directory.

Ensure all special files inside app/ are nested under app/[locale].

Step 2: Add the middleware file

In Next.js, create a file called middleware.js (or .ts if you are using TypeScript) inside the root directory. If you are using the src/ folder, place it in src/middleware.js (or .ts) instead. Add the createNextMiddleware() function to the file.

import { createNextMiddleware } from 'gt-next/middleware'
 
export default createNextMiddleware();
 
export const config = {
  matcher: [
    /*
      * Match all request paths except for the ones starting with:
      * - api (API routes)
      * - _next (internal files)
      * - static files
      */
    "/((?!api|static|.*\\..*|_next).*)",
  ],
}

Set up localized paths

You can specify localized paths through the pathConfig option in the middleware file.

export default createNextMiddleware({
  pathConfig: {
    // You can specify a shared path (optional)
    // This will create "/en/about" and "/zh/about"
    "/about": "/about",
 
    // Specify localized paths
    // This will create "/en/airplanes" and "/zh/飞机"
    "/airplanes": {
      "zh": "/飞机",
    }
 
    // Add dynamic path parameters
    // This will create "/en/airports/123" and "/zh/飞机机场/123"
    "/airports/[id]": {
      "zh": "/飞机机场/[id]",
    }
  },
});

In this example we create a default path for /en/about and localized paths for /en/airplanes and /en/airports/[id]. In Chinese, these will be aliased to /zh/about, /zh/飞机 and /zh/飞机机场/[id] respectively.

Routing behavior

Default locale prefixing

By default, your defaultLocale (a.k.a. your app's default language) will not be prefixed with a locale code in the url. For example, if your default locale is en and you have a page at /about, it will be accessible at /about in English. However, in Chinese, it will be accessible at /zh/about in Chinese.

If you do not want this behavior, it can be disabled by setting the prefixDefaultLocale to false in the middleware configuration.

Locale detection and redirection

The middleware will detect the user's locale based on (1) the url path locale, (2) the referrer locale, (3) the accepted languages from the browser, and (4) finally the defaultLocale. The user will then be redirected accordingly.

If at any time a localized version of the page exists, they will be redirected to the localized url. For instance, /zh/airplanes will always redirect to /zh/飞机.

Edge case: Localized paths without locale prefix

If you navigate to a localized path without the locale prefix (e.g., /飞机), the middleware will prefix that path with whatever it thinks your current locale is.

For example, visiting /飞机 will only redirect to /zh/飞机 if the middleware explicitly recognizes your locale as zh. This is great but it only works when the middleware thinks your locale is zh.

Otherwise, your path will be prefixed with your current locale. For example, visiting /飞机 will redirect to /en/飞机 if the middleware thinks your locale is en. This will result in a 404.

We recommend always using the path from your defaultLocale for any links in your project. This will always automatically redirect to the correct locale localized path.

<Link href="/about">About</Link>
<Link href="/planes">Planes</Link>
<Link href="/airports/123">Airport 123</Link>

If you want to explicitly link to a different locale, then you can do so by using the localized path.

<Link href="/zh/about">About in Chinese</Link>
<Link href="/zh/飞机">Planes in Chinese</Link>
<Link href="/zh/飞机机场/123">Airport 123 in Chinese</Link>

Notes

• i18n routing changes the URL structure of your application. Each language has its own URL.
• The middleware file is required to handle the routing logic.
• You can specify the supported locales in the middleware configuration and next config file.

Next Steps

• See the API docs for createNextMiddleware().
• Read more about Locale Management.
• Learn how to Translate Your Application.