i18n for Next.js — Implementation Guide

Core Principles

• All user-facing features must implement i18n — no hardcoded strings in components.
• Translations must be natural and idiomatic — never use scripts or machine translation; treat quality the same as English copywriting.
• SEO metadata, JSON-LD structured data, and sitemaps must all be locale-aware.
• Default locale (English) uses clean URLs with no prefix (/products); other locales use a prefix (/es/products).

Supported Locales

Locale list lives in src/lib/i18n/locales.ts. Keep the sitemap script's locales array in sync with this file.

export const locales = ['en', 'es', 'fr', 'de', 'ja', 'zh-CN', /* ... add as needed */]
export const defaultLocale = 'en'
export type Locale = typeof locales[number]

Directory Structure

src/app/[lang]/
├── dictionaries/       ← One JSON file per locale
│   ├── en.json
│   ├── es.json
│   └── ...
├── dictionaries.ts     ← getDictionary(locale) server helper
├── layout.tsx          ← Root layout: generateMetadata + hreflang + JSON-LD
└── <page>/
    └── page.tsx        ← generateMetadata + page content

Translation Files

See references/translation-files.md for:

• JSON key hierarchy conventions (page.section.key)
• Server-side getDictionary() usage
• Client-side useDictionary() hook usage
• Template variable pattern ({count} substitution)
• Fallback pattern for missing keys

Routing & Middleware

See references/routing.md for:

• src/middleware.ts — locale detection, redirect /en/* → /*, rewrite for default locale
• LocalizedLink component — automatically prefixes non-default locales
• useLocale() hook — reads locale from URL params → pathname → localStorage → default
• getLocalizedPath() / removeLocalePrefix() utilities

SEO Metadata

See references/seo-metadata.md for:

• generateMetadata() pattern in layout/page files
• generateAlternatesMetadata() from src/lib/i18n/seo.ts
• Full hreflang alternates.languages output (all locales + x-default)
• OpenGraph locale / alternateLocale fields
• html lang attribute and LangSetter client component

Structured JSON-LD Data

See references/structured-data.md for:

• WebApplication schema with translated featureList, description
• BlogPosting schema with inLanguage field
• FAQ schema with translated acceptedAnswer
• BreadcrumbList schema with localized URLs
• Rendering via <Script> or <script> tags

Multi-language Sitemap

See references/sitemap.md for:

• Sitemap structure: one <url> entry per page with <xhtml:link> alternates for every locale
• <loc> uses the default-locale (clean) URL; x-default also points there
• Full XML example with static and dynamic pages
• Next.js App Router sitemap.ts implementation pattern
• What to include vs. exclude (admin/API routes excluded)
• Hreflang language code format rules

Quick Checklist — Adding a New Feature with i18n

1. Add translation keys to all locale JSON files in src/app/[lang]/dictionaries/
   • Add English first, then translate to all other languages naturally
2. Server components: const dict = await getDictionary(locale) → dict?.page?.section?.key || 'fallback'
3. Client components: const dict = useDictionary() → same fallback pattern
4. Add generateMetadata() to the page file, calling generateAlternatesMetadata()
5. Add JSON-LD structured data script tag with translated fields and inLanguage
6. Update sitemap if the page is new: add it to the sitemap source (see references/sitemap.md)
7. Use <LocalizedLink> for internal links and getLocalizedPath() for programmatic navigation

Quick Checklist — Adding a New Locale

1. Add locale code to locales array in src/lib/i18n/locales.ts
2. Add locale entry to dictionaries/ as <code>.json (full translation of en.json)
3. Add entry in src/app/[lang]/dictionaries.ts import map
4. Add display name in LanguageSwitcher languageNames map
5. Sync the sitemap locale list with the app's locales array
6. Regenerate / redeploy the sitemap