Adds multi-language support to Next.js websites with proper SEO configuration including hreflang tags, localized sitemaps, and language-specific content. Use when adding new languages, setting up i18n, optimizing for international SEO, or when user mentions localization, translation, multi-language, or specific languages like Japanese, Korean, Chinese.
Complete workflow for adding multi-language support to Next.js websites with SEO best practices.
Common target markets:
Extended support available for:
Copy this checklist and track your progress:
i18n Progress:
- [ ] Step 1: Prepare base language files
- [ ] Step 2: Add new language files
- [ ] Step 3: Update configuration files
- [ ] Step 4: Add translations
- [ ] Step 5: Configure SEO elements
- [ ] Step 6: Validate and test
Ensure English (en.json) files exist as templates:
Required directories:
i18n/messages/en.json - Main translationsi18n/pages/landing/en.json - Landing page translationsVerify structure:
# Check if base files exist
ls i18n/messages/en.json
ls i18n/pages/landing/en.json
If missing, create them with complete translation keys for your website.
Run the language addition script:
node scripts/i18n-add-languages.mjs
What this script does:
en.json to all target language filesi18n/locale.ts with new localesi18n/request.ts with language mappingspublic/sitemap.xml with new language URLsScript configuration (in i18n-add-languages.mjs):
languages array - List of languages to addlanguageNames object - Language display namestargetDirs array - Directories containing translation filesSee WORKFLOW.md for detailed step-by-step guide.
Check i18n/locale.ts:
export const locales = ["en", "ja", "zh", "ko", ...];
export const localeNames: any = {
en: "English",
ja: "日本語",
zh: "中文",
ko: "한국어",
...
};
Check i18n/request.ts:
zh-CN → zh, zh-HK → zh-hk mappings presentCheck public/sitemap.xml:
hreflang tags present for each URLOption A: Using AI translation (faster but needs review):
# Add structured data and pricing translations
node scripts/i18n-add-schema.js
Configure translations in the script's translations object.
Option B: Manual translation (recommended for quality):
Edit each language file with proper translations:
# Open language file
code i18n/messages/ja.json
Translation best practices:
See reference/locale-codes.md for language code reference.
hreflang tags - Automatic via sitemap, but verify:
See reference/hreflang-guide.md for complete guide.
Localized meta tags - Translate in each language file:
{
"metadata": {
"title": "Your Site Title",
"description": "Your SEO description"
}
}
URL structure - Verify correct format:
https://example.com/ or https://example.com/en/https://example.com/ja/https://example.com/zh/Build the project:
npm run build
CRITICAL: Fix any errors before proceeding.
Manual testing:
Language switcher:
Content display:
SEO elements:
<html lang="..."> attribute matches page language<link rel="alternate" hreflang="..."> tags presentAutomated validation:
# Check sitemap
curl https://your-site.com/sitemap.xml | grep hreflang
# Validate hreflang (use online tool)
# Google Search Console > Internationalization > hreflang
SEO checklist - See reference/seo-checklist.md.
If validation fails:
Only proceed when all validations pass.
Use ISO 639-1 (two-letter codes) with optional regional variants:
en - Englishja - Japanesezh - Simplified Chinesezh-hk - Traditional Chinese (Hong Kong)pt - Portuguesept-br - Brazilian PortugueseSee reference/locale-codes.md for complete list.
Correct i18n improves SEO by:
Common SEO mistakes to avoid:
AI translation vs Human translation:
Recommended approach:
The system uses next-intl for routing:
Configuration in i18n/locale.ts and i18n/request.ts.
After adding languages:
All i18n scripts are in the scripts/ directory:
i18n-add-languages.mjs - Add new language filesi18n-add-schema.js - Add structured data translationsFor troubleshooting, see WORKFLOW.md troubleshooting section.