Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/shuding/nextra/llms.txt

Use this file to discover all available pages before exploring further.

Nextra supports Next.js Internationalized Routing out of the box, allowing you to serve documentation in multiple languages from the same codebase. You define your locales in next.config.mjs, organize content into per-locale directories, and configure the language switcher dropdown in your theme layout.
i18n support is only available in nextra-theme-docs. It is not supported in the blog theme.

​
Setup

1
Add i18n config to next.config.mjs
2
Pass an i18n block to your Next.js config, listing all supported locales and the default:
3
import nextra from 'nextra'

const withNextra = nextra({})

export default withNextra({
  i18n: {
    locales: ['en', 'zh', 'de'],
    defaultLocale: 'en'
  }
})
4
You can use any valid UTS Locale Identifier for your locale codes, including region variants like en-US or zh-TW.
5
Configure the language dropdown in your layout
6
Pass the i18n prop to the <Layout> component in your root layout.tsx to wire up the language-switcher dropdown that appears in the navbar:
7
import { Layout } from 'nextra-theme-docs'

export default function RootLayout({ children, params }) {
  return (
    <Layout
      i18n={[
        { locale: 'en', name: 'English' },
        { locale: 'zh', name: '中文' },
        { locale: 'de', name: 'Deutsch' },
        { locale: 'ar', name: 'العربية', direction: 'rtl' }
      ]}
      {/* ...other props */}
    >
      {children}
    </Layout>
  )
}
8
The optional direction: 'rtl' key enables right-to-left text layout for locales like Arabic.
9
Organize content by locale
10
Create a sub-directory inside content/ for each locale and place your translated MDX files there:
11
content/
├── en/
│   ├── _meta.js
│   ├── index.mdx
│   └── getting-started.mdx
├── zh/
│   ├── _meta.js
│   ├── index.mdx
│   └── getting-started.mdx
└── de/
    ├── _meta.js
    ├── index.mdx
    └── getting-started.mdx
12
Each locale directory can have its own _meta.js file to control sidebar ordering and titles in that language.
13
(Optional) Add automatic locale detection
14
To redirect users to their preferred language automatically, create a proxy.ts (or proxy.js) file at the root of your project and re-export Nextra’s middleware:
15
export { middleware } from 'nextra/locales'

export const config = {
  matcher: ['/((?!_next|_static|_vercel|[\\w-]+\\.\\w+).*)']
}
16
Automatic locale detection via middleware does not work for sites statically exported with output: 'export' in nextConfig.
17
(Optional) Add a custom 404 page
18
For i18n sites using a shared theme layout, you can add a locale-aware custom not-found page. See the SWR i18n example for a reference implementation.
The unstable_shouldAddLocaleToLinks option in your Nextra config controls whether locale prefixes are automatically added to links in the page map. This is useful when you are not using Nextra’s built-in middleware for locale detection: 
import nextra from 'nextra'

const withNextra = nextra({
  unstable_shouldAddLocaleToLinks: true
})

export default withNextra({
  i18n: {
    locales: ['en', 'zh', 'de'],
    defaultLocale: 'en'
  }
})

​
Per-Locale _meta.js Files

Each locale directory can contain a _meta.js file to customize the sidebar navigation for that language. This lets you set translated titles and control page order independently per locale: 
export default {
  index: '首页',
  'getting-started': '快速开始',
  advanced: {
    title: '高级',
    type: 'menu',
    items: {
      latex: 'LaTeX',
      mermaid: 'Mermaid'
    }
  }
}

​
Configuration Reference

OptionTypeDefaultDescription
i18n.localesstring[]—List of supported locale codes.
i18n.defaultLocalestring—The locale used when no locale prefix is present in the URL.
unstable_shouldAddLocaleToLinksbooleanfalsePrefix locale to all links in the page map — useful when not using Nextra’s middleware function.

Build docs developers (and LLMs) love

Get started for freeTalk to us