| name | Next.js Internationalization (i18n) |
|---|---|
| description | Best practices for multi-language handling, locale routing, and detection middleware. |
| metadata | {"labels": ["nextjs", "i18n", "middleware", "routing"], "triggers": {"files": ["middleware.ts", "app/[lang]/**", "messages/*.json"], "keywords": ["i18n", "locale", "translation", "next-intl", "redirect"]}} |
Internationalization (i18n)
Priority: P2 (MEDIUM)
Use Sub-path Routing (/en, /de) and Server Components for translations.
Principles
- Sub-path Routing: Use URL segments (e.g.,
app/[lang]/page.tsx) to manage locales. - Why: SEO friendly, sharable, and cacheable. - Server-Side Translation: Load dictionary files (
en.json) in Server Components. - Why: Reduces client bundle size. No huge JSON blobs sent to browser. - Middleware Detection: Use
middleware.tsto detectAccept-Languageheaders and redirect users to their preferred locale. - Type Safety: Use robust typing for translation keys to prevent broken text UI.
Implementation Pattern
See 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.jsfor legacy SEO 301s (e.g., old-site/about-us->/en/about).