# Next.js Internationalization (i18n)

> Best practices for multi-language handling, locale routing, and detection middleware.

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

---


# Internationalization (i18n)

## **Priority: P2 (MEDIUM)**

Use Sub-path Routing (`/en`, `/de`) and Server Components for translations.

## Principles

1. **Sub-path Routing**: Use URL segments (e.g., `app/[lang]/page.tsx`) to manage locales.
   - _Why_: SEO friendly, sharable, and cacheable.
2. **Server-Side Translation**: Load dictionary files (`en.json`) in Server Components.
   - _Why_: Reduces client bundle size. No huge JSON blobs sent to browser.
3. **Middleware Detection**: Use `middleware.ts` to detect `Accept-Language` headers and redirect users to their preferred locale.
4. **Type Safety**: Use robust typing for translation keys to prevent broken text UI.

## Implementation Pattern

See [references/i18n_setup.md](references/i18n_setup.md) for Directory Structure, Middleware, and Server Component examples.

## Redirect Handling Strategy

When handling redirects (Authentication, Legacy URLs) in an i18n app:

- **Always preserve locale**: Use `redirect(`/${lang}/login`)` instead of just `/login`.
- **Server Actions**: Return `redirect(...)` from actions.
- **Next Config**: Use `next.config.js` for legacy SEO 301s (e.g., old-site `/about-us` -> `/en/about`).