internationalizing-websites

name	Internationalizing Websites
description	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.

Internationalizing Websites

Complete workflow for adding multi-language support to Next.js websites with SEO best practices.

When to use this Skill

• Adding new language versions to existing website
• Setting up i18n (internationalization) for new website
• Configuring SEO for multiple languages
• User mentions: "add language", "translation", "localization", "hreflang", "multi-language"

Supported Languages

Common target markets:

• 🇺🇸 English (en) - Global market
• 🇯🇵 Japanese (ja) - Asian market
• 🇨🇳 Chinese (zh) - Chinese market

Extended support available for:

• Korean (ko), Portuguese (pt), Spanish (es), French (fr), German (de)
• Arabic (ar), Vietnamese (vi), Hindi (hi), Indonesian (id), Thai (th)
• Traditional Chinese (zh-hk), Italian (it), Russian (ru)

Internationalization Workflow

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

Step 1: Prepare base language files

Ensure English (en.json) files exist as templates:

Required directories:

• i18n/messages/en.json - Main translations
• i18n/pages/landing/en.json - Landing page translations

Verify 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.

Step 2: Add new language files

Run the language addition script:

node scripts/i18n-add-languages.mjs

What this script does:

• Copies en.json to all target language files
• Updates i18n/locale.ts with new locales
• Updates i18n/request.ts with language mappings
• Updates public/sitemap.xml with new language URLs

Script configuration (in i18n-add-languages.mjs):

• languages array - List of languages to add
• languageNames object - Language display names
• targetDirs array - Directories containing translation files

See WORKFLOW.md for detailed step-by-step guide.

Step 3: Verify configuration updates

Check i18n/locale.ts:

export const locales = ["en", "ja", "zh", "ko", ...];

export const localeNames: any = {
  en: "English",
  ja: "日本語",
  zh: "中文",
  ko: "한국어",
  ...
};

Check i18n/request.ts:

• Language code mappings configured
• zh-CN → zh, zh-HK → zh-hk mappings present

Check public/sitemap.xml:

• All language versions listed
• hreflang tags present for each URL

Step 4: Add translations

Option 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:

• Use native speakers when possible
• Maintain SEO keywords in target language
• Adapt content to local culture, don't just translate
• Keep formatting consistent (placeholders, variables)

See reference/locale-codes.md for language code reference.

Step 5: Configure SEO elements

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:

• English: https://example.com/ or https://example.com/en/
• Japanese: https://example.com/ja/
• Chinese: https://example.com/zh/

Step 6: Validate and test

Build the project:

npm run build

CRITICAL: Fix any errors before proceeding.

Manual testing:

1. Language switcher:

   • Visit each language version
   • Verify language switcher shows all languages
   • Click each language link, verify correct page loads

2. Content display:

   • Check all pages render correctly in each language
   • Verify no untranslated text (check for English in non-English pages)
   • Test special characters display correctly (Japanese, Chinese, Arabic)

3. SEO elements:

   • Inspect <html lang="..."> attribute matches page language
   • Verify <link rel="alternate" hreflang="..."> tags present
   • Check meta tags are in correct language

Automated 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:

• Review error messages carefully
• Check configuration files for typos
• Verify language codes are correct
• Return to Step 3 and fix issues

Only proceed when all validations pass.

Important Notes

Language Code Standards

Use ISO 639-1 (two-letter codes) with optional regional variants:

• en - English
• ja - Japanese
• zh - Simplified Chinese
• zh-hk - Traditional Chinese (Hong Kong)
• pt - Portuguese
• pt-br - Brazilian Portuguese

See reference/locale-codes.md for complete list.

SEO Implications

Correct i18n improves SEO by:

• Targeting users in their native language
• Avoiding duplicate content penalties
• Helping search engines serve correct language version

Common SEO mistakes to avoid:

• ❌ Auto-redirect based on IP (prevents search engines from crawling all versions)
• ❌ Missing hreflang tags (causes duplicate content issues)
• ❌ Inconsistent URL structure across languages
• ❌ Untranslated meta tags

Translation Quality

AI translation vs Human translation:

• ✅ AI: Fast, cost-effective, good for initial draft
• ⚠️ AI: May miss cultural nuances, needs review
• ✅ Human: Better quality, cultural adaptation
• ⚠️ Human: Slower, more expensive

Recommended approach:

1. Use AI to generate initial translations
2. Have native speaker review and refine
3. Test with target market users
4. Iterate based on feedback

Next.js i18n Routing

The system uses next-intl for routing:

• Automatic locale detection from URL
• Language switcher component
• Localized navigation

Configuration in i18n/locale.ts and i18n/request.ts.

Post-Internationalization Tasks

After adding languages:

1. Submit updated sitemap to Google Search Console
2. Create separate Search Console properties for each language/region
3. Monitor international organic traffic in Analytics
4. A/B test translations if conversion rates differ by language
5. Set up alerts for international crawl errors

Script Locations

All i18n scripts are in the scripts/ directory:

• i18n-add-languages.mjs - Add new language files
• i18n-add-schema.js - Add structured data translations

Reference Materials

• WORKFLOW.md - Detailed step-by-step workflow
• reference/hreflang-guide.md - hreflang implementation guide
• reference/locale-codes.md - Language codes reference
• reference/seo-checklist.md - International SEO checklist

For troubleshooting, see WORKFLOW.md troubleshooting section.