Next.js I18n

⚠️

Warning

This feature is only available in nextra-theme-docs.

Nextra supports Next.js Internationalized Routing out of the box. These docs explain how to configure and use it.

Add I18n Config

To add multi-language pages to your Nextra application, you need to config i18n in next.config.mjs first:

next.config.mjs


import nextra from 'nextra'
 
const withNextra = nextra({
  // ... other Nextra config options
})
 
export default withNextra({
  i18n: {
    locales: ['en', 'zh', 'de'],
    defaultLocale: 'en'
  }
})

Note

You can use any format of UTS Locale Identifiers for defining your locales in the next.config file, e.g. language with region format en-US (English as spoken in the United States).

Configure the Docs Theme

Add the i18n option to your theme.config.jsx to configure the language dropdown:

theme.config.jsx


i18n: [
  { locale: 'en', name: 'English' },
  { locale: 'zh', name: '中文' },
  { locale: 'de', name: 'Deutsch' },
  { locale: 'ar', name: 'العربية', direction: 'rtl' }
]

Automatically Detect and Redirect to User-Selected Language (Optional)

You can automatically detect the user’s preferred language and redirect them to the corresponding version of the site. To achieve this, create a middleware.js file in the root of your project and export Nextra’s middleware function from nextra/locales:

middleware.js


export { middleware } from 'nextra/locales'
 
export const config = {
  // Matcher ignoring `/_next/` and `/api/`
  matcher: [
    '/((?!api|_next/static|_next/image|favicon.ico|icon.svg|apple-icon.png|manifest).*)'
  ]
}

⚠️

Warning

This approach will not work for i18n sites that are statically exported with output: 'export' in nextConfig.

Custom 404 Page (Optional)

In Nextra 3, it’s not possible to create a 404.mdx page for an i18n website that uses a shared theme layout. However, you can implement a 404.jsx page with translations. You can refer to the SWR i18n example for guidance on how to do this.

In Nextra 4, you can have a custom not-found.jsx with translations for an i18n website that uses a shared theme layout. For guidance on implementing this, you can check out the SWR i18n example .