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

2. Set Up Middleware (middleware.ts)

   • Auto-redirect to appropriate locale
   • Handle language detection

3. Restructure App Directory

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

4. Configure Language Switcher

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

5. Organize Content by Language

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

6. 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