Internationalization (i18n)

Priority: P2 (MEDIUM)

Maintain a single source of truth for locales and ensure SEO-friendly sub-path routing.

Workflow: Add i18n to a Next.js App Router Project

1. Install next-intl and create messages/en.json, messages/fr.json, etc.
2. Add locale detection middleware in middleware.ts
3. Create app/[lang]/layout.tsx with locale param
4. Load translations server-side via getMessages()
5. Add hreflang tags in generateMetadata
6. Pre-render locales with generateStaticParams
7. Verify: run next build and confirm all locale paths render

Middleware Example

See implementation examples

Implementation Guidelines

• Locale Routing: Follow the URL-first approach for SEO. Use dynamic segments in the App Router (app/[lang]/page.tsx) and the i18n configuration in next.config.js for the Pages Router.
• Library Selection: Use next-intl for the App Router (modern) or react-intl / next-translate for legacy apps.
• Detection: Implement middleware localization in middleware.ts to detect user language from Accept-Language headers or cookies and perform redirects.
• Server-Side: Load translation messages/*.json dictionaries in Server Components to keep the client bundle small.
• SEO: Ensure hreflang tags are generated correctly in the metadata API for all translated routes.
• Static Generation: Use generateStaticParams to pre-render localized versions of static pages at build time.

Library Specifics

For detailed setup with common libraries, refer to:

• references/react-intl.md
• references/next-intl.md

Anti-Patterns

• No hardcoded strings in JSX: Use translation keys; never commit raw text.
• No client-side translation bundles: Load dictionaries server-side with getMessages().
• No mixed URL locale patterns: Use sub-paths or domains consistently.