Orientation
Content Processing
Search Infrastructure
Rendering and UI
Developer Tooling
How It Works
The following files were used as context for generating this wiki page:
I18n Routing provides the infrastructure for multi-language support across the documentation system. It handles the critical tasks of detecting user locale, managing URL prefixes, and ensuring that page trees and content are correctly scoped to the active language. By integrating with Next.js middleware and specialized loaders, it ensures that users are consistently directed to the correct content translation.
The architecture centers on the I18nConfig definition and a dedicated middleware. The system uses a negotiator to determine the user's preferred language, which is then reconciled against the configured languages array. This process determines whether a URL rewrite (to keep the locale hidden) or a redirect (to establish the explicit locale in the URL) is necessary, effectively abstracting the complexity of localized pathing away from the UI components.
Beyond routing, the system bridges the gap between language configuration and UI components via context providers. These providers (e.g., I18nProvider) manage state such as the current locale and available translations, enabling language switchers and localized text rendering. The system is designed to scale across different packages, allowing UI layers to register translations that are then merged and injected into the React tree.
The createI18nMiddleware function is the gatekeeper for localized requests. It processes incoming URLs using a URLFormatter to identify potential locale codes in the pathname. If no locale is detected or the detected locale is invalid, it negotiates the preferred language based on request.headers using @formatjs/intl-localematcher.
The middleware implements three hideLocale strategies:
'never': The locale is always visible in the URL path.'default-locale': The locale prefix is stripped for the default language but visible for others.'always': The locale prefix is hidden entirely; the locale is tracked via a cookie (default: FD_LOCALE).Sources: packages/core/src/i18n/middleware.ts:56-110
Note
When hideLocale is set to always, the middleware performs a NextResponse.rewrite to the locale-prefixed URL if the user doesn't have a locale preference, otherwise it uses the locale found in the cookie.
Sources: packages/core/src/i18n/middleware.ts:89-93
The createContentStorageBuilder utility organizes source content by locale. It utilizes a configurable parser to map file system paths to internal virtual paths.
Sources: packages/core/src/source/storage/content.ts:54-87
The builder scan process separates files into locale-specific maps. If a fallbackLanguage is defined, the storage builder performs a chained lookup, inheriting files from the fallback storage when a missing translation is requested.
Sources: packages/core/src/source/storage/content.ts:153-167
The PageTreeBuilder creates the hierarchical structure used by sidebars. When initialized with locale support (as an array of [locale, storages]), it creates a PageTreeBuilderContext specific to that locale. This ensures that the tree built for /zh-TW correctly references only the content files assigned to that locale.
Sources: packages/core/src/source/page-tree/builder.ts:89-136
Tip
The builder relies on the own() function to prevent duplicate node registration when multiple folders reference the same file content; it uses a priority check to decide which folder "claims" the node.
Sources: packages/core/src/source/page-tree/builder.ts:158-184
Translations are defined using defineI18n and can be extended with specific keys via TranslationExtension. The API supports multiple language presets.
import { defineI18n } from 'fumadocs-core/i18n';
import { zhTW } from 'packages/language/src/zh-tw';
const i18n = defineI18n({
languages: ['en', 'zh-TW'],
defaultLanguage: 'en',
});
const t = i18n.translations().preset('zh-TW'Sources: packages/core/src/i18n/index.ts:120-165
The I18nProvider in both base-ui and radix-ui shares a common mechanism. It consumes the current locale and a change handler, providing these via React context. The onChange implementation computes the new path by replacing the existing locale segment in the URL or prepending a new one if necessary, ensuring the user stays on the same page while switching languages.
Sources: packages/base-ui/src/contexts/i18n.tsx:42-55
The search subsystem supports locale-specific indexing. createI18nSearchAPI initializes separate Orama search servers for each locale, allowing queries to be routed to the correct language index.
Sources: packages/core/src/search/orama/create-server.ts:190-237