Agent-Skills.md

Agent Skills: Internationalization (i18n)

Best practices for multi-language handling, locale routing, and detection strategies across App and Pages Router. Use when adding i18n, locale routing, or language detection in Next.js. (triggers: middleware.ts, app/[lang]/**, pages/[locale]/**, messages/*.json, next.config.js, i18n, locale, translation, next-intl, react-intl, next-translate)

UncategorizedID: hoangnguyen0403/agent-skills-standard/nextjs-i18n

Repository

hoangnguyen0403/agent-skills-standard
HoangNguyen0403License: Apache-2.0
362103

Install this agent skill to your local

pnpm dlx add-skill https://github.com/HoangNguyen0403/agent-skills-standard/tree/HEAD/skills/nextjs/nextjs-i18n

Skill Files

Browse the full folder contents for nextjs-i18n.

Download Skill

Loading file tree…

skills/nextjs/nextjs-i18n/SKILL.md

Skill Metadata

Name
nextjs-i18n
Description
"Best practices for multi-language handling, locale routing, and detection strategies across App and Pages Router. Use when adding i18n, locale routing, or language detection in Next.js. (triggers: middleware.ts, app/[lang]/**, pages/[locale]/**, messages/*.json, next.config.js, i18n, locale, translation, next-intl, react-intl, next-translate)"

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:

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.