Fumadocs Internationalization Setup

Automate the complete setup of internationalization (i18n) in a Fumadocs project with language routing, switcher UI, and proper content organization.

When to Use This Skill

Use this skill when:

• Setting up a new Fumadocs project with multi-language support
• Adding i18n to an existing Fumadocs project
• The user mentions: "add multi-language", "internationalization", "i18n", "translate docs"
• They want language-specific sidebars and navigation
• They need a language switcher in the UI

Prerequisites

Before using this skill, verify:

• Fumadocs project is initialized (with fumadocs-core, fumadocs-ui, fumadocs-mdx)
• Next.js App Router is being used
• Project has the following structure:

`` app/ ├── layout.tsx ├── (home)/ └── docs/ content/docs/ lib/ ``

What This Skill Does

This skill will automatically:

1. Create i18n Configuration (lib/i18n.ts)

- Define supported languages - Set default language - Configure directory parser

1. Set Up Middleware (middleware.ts)

- Auto-redirect to appropriate locale - Handle language detection

1. Restructure App Directory

- Move routes under [lang] dynamic segment - Update all layouts for i18n support

1. Configure Language Switcher

- Add language toggle to navigation - Set up display names and translations

1. Organize Content by Language

- Structure content/docs/ with language directories - Ensure sidebar only shows current language

1. Update All Configurations

- Modify source.ts for i18n - Update layout.shared.tsx to pass locale - Configure page trees per language

Supported Languages

Default configuration includes:

• English (en) - Default language
• Chinese (zh) - Simplified Chinese
• French (fr)
• Korean (ko)

You can customize this list based on user requirements.

Workflow

See the detailed README.md for step-by-step implementation guide.

Key Features

✅ Official fumadocs Approach - Follows fumadocs.dev documentation exactly ✅ Language Switcher - Beautiful dropdown in navigation bar ✅ Filtered Sidebar - Only shows content for current language ✅ SEO-Friendly URLs - Clean /[lang]/docs structure ✅ Automatic Detection - Middleware handles language routing ✅ Type-Safe - Full TypeScript support

Common Issues Solved

This skill addresses common fumadocs i18n pitfalls:

• ❌ Sidebar showing all languages → ✅ Filtered by source.pageTree[lang]
• ❌ Missing language switcher → ✅ Auto-configured in DocsLayout
• ❌ Wrong URL structure → ✅ Correct /[lang]/docs routing
• ❌ Content not organized → ✅ Proper en/, zh/, etc. directories
• ❌ Parser errors → ✅ parser: 'dir' configuration

Files Created/Modified

The skill will create or modify:

• lib/i18n.ts ← New
• middleware.ts ← New
• app/layout.tsx ← Modified
• app/[lang]/layout.tsx ← New
• app/[lang]/(home)/layout.tsx ← Moved
• app/[lang]/docs/layout.tsx ← Moved
• app/[lang]/docs/[[...slug]]/page.tsx ← Moved
• lib/source.ts ← Modified
• lib/layout.shared.tsx ← Modified
• content/docs/[lang]/ ← New structure

Success Criteria

After running this skill, the user should have:

• ✅ Language switcher visible in top-right navigation
• ✅ URLs like /en/docs, /zh/docs, /fr/docs, /ko/docs
• ✅ Sidebar showing only current language content
• ✅ Middleware redirecting root / to default language
• ✅ All content properly organized in language directories
• ✅ Build succeeds without errors
• ✅ Development server runs correctly

Version History

• v1.0.0 (2025-11-16): Initial release

- Complete i18n setup automation - Language switcher integration - Sidebar filtering by language - Content reorganization - Official fumadocs best practices