internationalization

Files (3)

• README.md
• SKILL.md
• locale-checklist.md · references/

SKILL.md (first lines)

# Internationalization

Add languages and regions in a way that works for users, search engines, and the team maintaining the content. Stack-agnostic.

---

## When to use

- Adding the first non-English (or non-default) language
- Adding additional locales to an existing internationalized site
- Choosing URL structure for languages
- Implementing hreflang tags
- Designing translation workflow
- Handling currency, date, time, and number formats
- Designing or fixing layout for RTL languages
- Auditing an internationalization rollout that's underperforming

## When NOT to use

- Single-language site (use other skills)
- Domain strategy that's not language-driven (use `domain-strategy`)
- Content strategy independent of locale (use `content-strategy`)
- Marketing copy production (use `content-and-copy`)

---

## Required inputs

- The locales in scope (language + region, e.g., `en-US`, `de-DE`, `fr-CA`)
- Business reason per locale (priority, audience size)
- Existing site architecture
- Translation resources (in-house, agency, AI-assisted, community)
- Content volume and update frequency

---

## The framework: 5 layers

Internationalization touches everything. Five layers, each with their own decisions.

### Layer 1: URL structure

How locales are reflected in URLs.

| Pattern | Example | When |
|---|---|---|
| ccTLD | example.de, example.fr | Strong country focus, distinct legal entities, willing to maintain separate domains |
| Subdomain | de.example.com, fr.example.com | Logical separation, willing to host separately, common for large sites |
| Subfolder | example.com/de/, example.com/fr/ | SEO equity unified, simplest to manage, default for most |
| URL parameter | example.com?lang=de | Avoid; weak SEO signal |

For most sites: subfolder is the default. Subdomain or ccTLD only when there's a specific reason (legal, infrastructure, or brand).

Within the chosen pattern, decide:
- Language only (`/de/`) or language plus region (`/de-de/`, `/de-at/`, `/de-ch/`)?
- Default locale: at the apex (`example.com`) or in a folder (`example.com/en/`)?

The default-locale-at-apex pattern is common but causes hreflang complexity (the apex needs an `x-default` and the canonical for the default language).

### Layer 2: Content structure

How content is organized across locales.

**Pattern A: Mirror.** Every page in every locale. The translation IS the page. Suitable for marketing sites with controlled content.

**Pattern B: Subset.** Some content in all locales, some only in select locales. Common for product pages (only available products), blog (some posts translated), or regulatory differences.

**Pattern C: Local.** Each locale has its own content largely independent of other locales. Common for media or community sites.

Most marketing sites are A. Most large sites end up at B by necessity. C is for sites with strong regional editorial.

The pattern affects:
- How content models are designed (does each piece have parent/translation relationships?)
- How translation is managed (workflow assumes the structure)
- How the team coordinates

### Layer 3: hreflang and canonicals

Telling search engines what's translated vs distinct.

**hreflang** specifies the language and optional region for each version.

```html
<link rel="alternate" hreflang="en-US" href="https://example.com/en-us/page">
<link rel="alternate" hreflang="en-GB" href="https://example.com/en-gb/page">
<link rel="alternate" hreflang="de-DE" href="https://example.com/de-de/page">
<link rel="alternate" hreflang="x-default" href="https://example.com/en-us/page">
```

Rules:
- Every page lists every translated equivalent (including itself)
- Pages must reciprocate (page A says page B is its German version; page B says page A is its English version)
- `x-default` is the fallback for users in unspecified regions
- Each page has its own canonical pointing to itself (not to the default language)

hreflang can be in the HTML head, in HTTP headers, or in the XML sitemap. Sitemap is best for large sites; HTML head is fine for small.

**Canonicals:**
- Self-referential per page
- Don't canonical the German page to the English page (search engines won't index the German page)

### Layer 4: Translation workflow

How content gets translated, kept fresh, and quality-controlled.

**Sources of translation:**
- In-house translators (full-time staff)
- Translation agency (paid per word, professional)
- Community contributors (volunteer, variable quality, free)
- AI-assisted plus human review (cheap, fast, growing in quality)
- AI only (acceptable for some content, not for brand-critical)

**Workflow stages:**

1. **Source content authored** in the source language
2. **Translation requested** through a TMS (translation management system) or spreadsheet
3. **Translation produced** with translation memory (avoids retranslating reused phrases)
4. **Review** by a second translator or in-region staff
5. **Localization** beyond translation (currency, units, examples, cultural references)

From rampstackco/claude-skills, MIT.

More from rampstackco/claude-skills