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