playbooks

home / skills / hoangnguyen0403 / agent-skills-standard / internationalization

internationalization skill

/skills/nextjs/internationalization

This skill helps implement Next.js i18n with sub-path routing, server components, and language detection to improve localization and SEO.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill internationalization

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
1.5 KB
---
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

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`).

Overview

This skill captures best practices for implementing internationalization (i18n) in Next.js apps using sub-path routing, server components, and middleware detection. It focuses on SEO-friendly URL structures, server-side translation loading, redirect handling, and type-safe translation keys to avoid runtime UI breakage. Followable patterns and concrete guidance help keep client bundles small and locale behavior predictable.

How this skill works

Locale routing is implemented with sub-paths (for example, app/[lang]/page.tsx) so each language has its own URL segment for SEO and caching. Server Components load locale dictionaries (e.g., en.json) at render time to avoid shipping large JSON to the browser. A middleware.ts inspects Accept-Language headers and redirects users to the most appropriate /[lang] path. Redirects and server actions preserve the locale by always including the language segment in target paths.

When to use it

  • Multi-language public sites that need SEO-friendly URLs and shareable links.
  • Apps where minimizing client bundle size and avoiding heavy runtime translation payloads is important.
  • Projects requiring consistent redirect logic across authentication and legacy URL flows.
  • Teams that want compile-time safety for translation keys to prevent UI regressions.
  • When you need automatic locale detection for first-time visitors based on headers.

Best practices

  • Use sub-path routing (app/[lang]/...) rather than domain or query-based locale switching for SEO and caching.
  • Load translation dictionaries in Server Components to reduce client payload and simplify hydration.
  • Implement middleware.ts to detect Accept-Language and perform a first-visit redirect to /[lang].
  • Always preserve the current locale in redirects (e.g., redirect(`/${lang}/login`) not `/login`).
  • Type your translation keys and dictionaries so missing keys are caught at build or compile time.
  • Configure next.config.js for legacy 301 redirects that map old URLs to localized targets.

Example use cases

  • A marketing site with English and German pages using /en and /de for SEO and canonical links.
  • An authenticated app that redirects to localized login pages while preserving the locale segment.
  • A large site migrating old URLs to localized equivalents via next.config.js 301 mappings.
  • A performance-sensitive app that renders server-side translations to keep client bundles minimal.

FAQ

Should I use sub-paths or domains for locales?

Use sub-paths for most cases: they are simpler to manage, SEO-friendly, and work with caching and sharing links. Domains are useful for geolocation/brand reasons but add operational complexity.

How do I avoid shipping large JSON translation files to the client?

Load dictionaries in Server Components so translations render server-side. Only send minimal runtime data to the client and avoid bundling full locale JSON blobs.