# Fumadocs I18N

> Set up complete internationalization (i18n) for a Fumadocs project following official best practices. Configures multi-language routing, language switcher, sidebar filtering, and proper content organization for Next.js. Use this skill when the user wants to add i18n support to their Fumadocs documentation site.

- Skill: `foreveryh/fumadocs-i18n` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add foreveryh/fumadocs-i18n`
- Raw SKILL.md: https://api.skillmd.com/api/skills/foreveryh/fumadocs-i18n/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: foreveryh (https://skillmd.com/u/foreveryh)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/foreveryh/fumadocs-i18n

---


# 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