Internationalizing Websites Agent Skill

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:

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

• 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)

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

• Use AI to generate initial translations
• Have native speaker review and refine
• Test with target market users
• 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:

• Submit updated sitemap to Google Search Console
• Create separate Search Console properties for each language/region
• Monitor international organic traffic in Analytics
• A/B test translations if conversion rates differ by language
• 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.