Strategies: Localization
Guides localization strategy for AI/SaaS products expanding into global markets. Covers i18n implementation, translation, pricing, and marketing adaptation--not just text translation.
When invoking: On first use, if helpful, open with 1-2 sentences on what this skill covers and why it matters, then provide the main output. On subsequent use or when the user asks to skip, go directly to the main output.
Initial Assessment
Check for project context first: If .claude/project-context.md or .cursor/project-context.md exists, read it for product, target markets, and brand.
Identify:
- Target markets: Priority languages/regions
- Product type: SaaS, AI tool, content
- Technical stack: Next.js, React, etc.
Localization vs. Translation
Localization includes:
- Product: Features, UI/UX, cultural adaptation
- Pricing: True localization (adjust by market) vs. cosmetic (currency only)
- Marketing: Channels, content, user personas
- Compliance: GDPR, local regulations
Technical (i18n)
URL Structure
Choose one; be consistent:
| Option |
Example |
Pros / Cons |
| Subdirectories |
/en/, /de/, /zh/ |
Recommended; maintains domain authority |
| Subdomains |
de.example.com |
Separate hosting; less authority transfer |
| ccTLD |
example.de |
Strongest geo signal; costly |
- Use subdirectories, not subdomains for i18n; subdomains transfer less authority.
- Default locale: Root path for default (e.g.
/ for English); prefix for others (/zh/, /de/).
- IETF BCP 47: Use valid codes (
en, en-US, zh-CN, pt-BR). Same language, different country (e.g. de-DE vs de-AT) needs ≥20% content difference for Google to differentiate.
i18n SEO Principles
- No hardcoded strings: All user-facing text via translation dictionary.
- Symmetric alternates: Every locale page lists ALL other versions (including self-reference). ~75% of international sites have hreflang errors; missing reciprocal links is the most common.
- x-default: Always include for fallback when user language/location doesn't match any version.
- Canonical alignment: Canonical must match the same regional version hreflang refers to; misalignment causes Google to ignore hreflang.
- Full SEO coverage: Metadata, OpenGraph, JSON-LD (
inLanguage), and sitemap all locale-aware.
Common Issues (Next.js + next-intl)
| Issue |
Solution |
| Route conflict |
generateStaticParams(); validate locale |
| Auto redirect |
localeDetection: false |
| Middleware |
Apply only to prefixed paths (e.g. /zh) |
| URL duplication |
Manual switcher; getLocalizedHref() |
SEO
- Hreflang on all language versions; self-reference + symmetric annotations.
- Language switcher: Use
<a> not <button>; links in initial HTML.
- Canonical: Handle multi-domain if using local TLDs; align with hreflang.
- SPAs: Use sitemap-based hreflang as backup when HTML head is JS-rendered. See rendering-strategies.
Keyword Research by Market
| Market |
Tool |
| Russia |
Yandex Wordstat |
| Korea |
Naver DataLab |
| Global |
Google Keyword Planner, SEO tools |
Consider: Cultural expressions, search habits, competition, long-tail in small markets.
Terminology & Translation
- Translation workflow, glossary, style guide: See translation for full workflow
- Avoid machine translation for product/marketing: See translation (Human vs MT)
Pricing Strategies
| Strategy |
Use |
| True localization |
Adjust price by purchasing power |
| Cosmetic |
Display currency only; same price |
| Tools |
Parity Deals, Chargebee |
i18n SEO Checklist (New Feature / New Locale)
New feature with i18n
- Add translation keys to all locale JSON files. Use translation for glossary, style guide, and translation workflow.
- Add
generateMetadata() with alternates (hreflang) per page.
- Add JSON-LD with
inLanguage and translated fields.
- Add page to sitemap with hreflang annotations.
- Set
lang attribute on <html>; UTF-8 encoding.
New locale
- Add locale code to config; create
{code}.json dictionary.
- Register in sitemap locale list; regenerate.
- Add OpenGraph
locale and alternateLocale.
- Ensure all alternates are symmetric (every page lists all versions).
Multilingual Risks
- Batch publishing: Too many translated pages at once can trigger de-indexing or thin-content penalties.
- Mitigation: Roll out slowly; ensure content is product/industry relevant; avoid Wikipedia-like breadth; monitor indexing in GSC.
Avoid
- IP-based redirects that override user preferences.
- Machine translation without localization for product/marketing (see translation).
- Missing reciprocal hreflang between language versions.
- Canonical tags that conflict with hreflang.
Output Format
- Market priority
- i18n approach
- Keyword strategy per market
- Pricing recommendation
- Technical checklist
- i18n SEO checklist (if applicable)
Related Skills
- pricing-strategy: Base price structure; localization-strategy covers pricing by market
- page-metadata: Hreflang implementation
- url-structure: URL hierarchy for i18n (subdirectories, subdomains)
- content-strategy: Multilingual content planning; avoid thin translations
- translation: Translation workflow, glossary, style guide, human vs MT; produces content for localized pages
- navigation-menu-generator: Language switcher SEO
- affiliate-marketing: Local affiliates for target markets
- gtm-strategy: New market entry; localization as GTM for new geography
1---
2name: localization-strategy
3description: When the user wants to plan or implement localization strategy for multilingual and global growth. Also use when the user mentions "localization," "multilingual," "i18n," "global expansion," "market entry," "localization strategy," "hreflang," "multi-language SEO," or "international SEO." For translation workflow, glossary, and style guide, use translation.
4metadata:
5 version: 1.1.0
6---
7
8# Strategies: Localization
9
10Guides localization strategy for AI/SaaS products expanding into global markets. Covers i18n implementation, translation, pricing, and marketing adaptation--not just text translation.
11
12**When invoking**: On **first use**, if helpful, open with 1-2 sentences on what this skill covers and why it matters, then provide the main output. On **subsequent use** or when the user asks to skip, go directly to the main output.
13
14## Initial Assessment
15
16**Check for project context first:** If `.claude/project-context.md` or `.cursor/project-context.md` exists, read it for product, target markets, and brand.
17
18Identify:
191. **Target markets**: Priority languages/regions
202. **Product type**: SaaS, AI tool, content
213. **Technical stack**: Next.js, React, etc.
22
23## Localization vs. Translation
24
25Localization includes:
26- **Product**: Features, UI/UX, cultural adaptation
27- **Pricing**: True localization (adjust by market) vs. cosmetic (currency only)
28- **Marketing**: Channels, content, user personas
29- **Compliance**: GDPR, local regulations
30
31## Technical (i18n)
32
33### URL Structure
34
35Choose one; be consistent:
36
37| Option | Example | Pros / Cons |
38|--------|---------|-------------|
39| **Subdirectories** | `/en/`, `/de/`, `/zh/` | Recommended; maintains domain authority |
40| **Subdomains** | `de.example.com` | Separate hosting; less authority transfer |
41| **ccTLD** | `example.de` | Strongest geo signal; costly |
42
43- **Use subdirectories, not subdomains** for i18n; subdomains transfer less authority.
44- **Default locale**: Root path for default (e.g. `/` for English); prefix for others (`/zh/`, `/de/`).
45- **IETF BCP 47**: Use valid codes (`en`, `en-US`, `zh-CN`, `pt-BR`). Same language, different country (e.g. `de-DE` vs `de-AT`) needs ≥20% content difference for Google to differentiate.
46
47### i18n SEO Principles
48
49- **No hardcoded strings**: All user-facing text via translation dictionary.
50- **Symmetric alternates**: Every locale page lists ALL other versions (including self-reference). ~75% of international sites have hreflang errors; missing reciprocal links is the most common.
51- **x-default**: Always include for fallback when user language/location doesn't match any version.
52- **Canonical alignment**: Canonical must match the same regional version hreflang refers to; misalignment causes Google to ignore hreflang.
53- **Full SEO coverage**: Metadata, OpenGraph, JSON-LD (`inLanguage`), and sitemap all locale-aware.
54
55### Common Issues (Next.js + next-intl)
56
57| Issue | Solution |
58|-------|----------|
59| Route conflict | `generateStaticParams()`; validate locale |
60| Auto redirect | `localeDetection: false` |
61| Middleware | Apply only to prefixed paths (e.g. `/zh`) |
62| URL duplication | Manual switcher; `getLocalizedHref()` |
63
64### SEO
65
66- **Hreflang** on all language versions; self-reference + symmetric annotations.
67- **Language switcher**: Use `<a>` not `<button>`; links in initial HTML.
68- **Canonical**: Handle multi-domain if using local TLDs; align with hreflang.
69- **SPAs**: Use sitemap-based hreflang as backup when HTML head is JS-rendered. See **rendering-strategies**.
70
71## Keyword Research by Market
72
73| Market | Tool |
74|--------|------|
75| **Russia** | Yandex Wordstat |
76| **Korea** | Naver DataLab |
77| **Global** | Google Keyword Planner, SEO tools |
78
79Consider: Cultural expressions, search habits, competition, long-tail in small markets.
80
81## Terminology & Translation
82
83- **Translation workflow, glossary, style guide**: See **translation** for full workflow
84- **Avoid machine translation** for product/marketing: See **translation** (Human vs MT)
85
86## Pricing Strategies
87
88| Strategy | Use |
89|----------|-----|
90| **True localization** | Adjust price by purchasing power |
91| **Cosmetic** | Display currency only; same price |
92| **Tools** | Parity Deals, Chargebee |
93
94## i18n SEO Checklist (New Feature / New Locale)
95
96### New feature with i18n
97
981. Add translation keys to all locale JSON files. Use **translation** for glossary, style guide, and translation workflow.
992. Add `generateMetadata()` with alternates (hreflang) per page.
1003. Add JSON-LD with `inLanguage` and translated fields.
1014. Add page to sitemap with hreflang annotations.
1025. Set `lang` attribute on `<html>`; UTF-8 encoding.
103
104### New locale
105
1061. Add locale code to config; create `{code}.json` dictionary.
1072. Register in sitemap locale list; regenerate.
1083. Add OpenGraph `locale` and `alternateLocale`.
1094. Ensure all alternates are symmetric (every page lists all versions).
110
111### Multilingual Risks
112
113- **Batch publishing**: Too many translated pages at once can trigger de-indexing or thin-content penalties.
114- **Mitigation**: Roll out slowly; ensure content is product/industry relevant; avoid Wikipedia-like breadth; monitor indexing in GSC.
115
116### Avoid
117
118- IP-based redirects that override user preferences.
119- Machine translation without localization for product/marketing (see **translation**).
120- Missing reciprocal hreflang between language versions.
121- Canonical tags that conflict with hreflang.
122
123## Output Format
124
125- **Market** priority
126- **i18n** approach
127- **Keyword** strategy per market
128- **Pricing** recommendation
129- **Technical** checklist
130- **i18n SEO** checklist (if applicable)
131
132## Related Skills
133
134- **pricing-strategy**: Base price structure; localization-strategy covers pricing by market
135- **page-metadata**: Hreflang implementation
136- **url-structure**: URL hierarchy for i18n (subdirectories, subdomains)
137- **content-strategy**: Multilingual content planning; avoid thin translations
138- **translation**: Translation workflow, glossary, style guide, human vs MT; produces content for localized pages
139- **navigation-menu-generator**: Language switcher SEO
140- **affiliate-marketing**: Local affiliates for target markets
141- **gtm-strategy**: New market entry; localization as GTM for new geography
gabrielmoreira