---
id: littleben/awesomeAgentskills/internationalizing-websites
version: "85bd3aef"
license: MIT
install: manual
updated: 2026-01-17
---

# Internationalizing Websites — This skill guides you through adding multiple language versions to Next.js websites while maintaining search engine optimization. It covers preparing translation files, configuring language routing, setting up hreflang tags and localized sitemaps, and validating your setup across all language versions. The workflow includes automated scripts for adding languages and a comprehensive testing checklist to ensure proper SEO implementation.

Publisher: littleben · Stars: 183 · Updated: 2026-01-17

Install (manual): `git clone https://github.com/littleben/awesomeAgentskills`

## SKILL.md

# 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**:
```bash
# 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:

```bash
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](WORKFLOW.md) for detailed step-by-step guide.

### Step 3: Verify configuration updates

**Check `i18n/locale.ts`**:
```typescript
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):
```bash
# 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:
```bash
# 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](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](reference/hreflang-guide.md) for complete guide.

**Localized meta tags** - Translate in each language file:
```json
{
  "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**:
```bash
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**:
```bash
# 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](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](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](WORKFLOW.md) - Detailed step-by-step workflow
- [reference/hreflang-guide.md](reference/hreflang-guide.md) - hreflang implementation guide
- [reference/locale-codes.md](reference/locale-codes.md) - Language codes reference
- [reference/seo-checklist.md](reference/seo-checklist.md) - International SEO checklist

For troubleshooting, see [WORKFLOW.md](WORKFLOW.md) troubleshooting section.


[View on SkillFed](https://skillfed.io/littleben/awesomeAgentskills/internationalizing-websites) · [View on GitHub](https://github.com/littleben/awesomeAgentskills)