internationalization skill
✓ VerifiedPlan and execute multi-language and multi-region site strategies including URL structures, hreflang implementation, and translation workflows.
- GitHub stars
- 1,066
- Files
- 3
- Last commit
- Nov 8, 2026
- License
- MIT
- Allowed tools
- —
What does the internationalization skill do?
internationalization is an agent skill. Plan and execute multi-language and multi-region site strategies including URL structures, hreflang implementation, and translation workflows.
Summary generated from the skill's SKILL.md.
About the internationalization skill
Planning and managing multi-language or multi-region websites is what this skill enables for developers and site owners. It provides a framework for adding new locales, selecting appropriate URL structures like subfolders, subdomains, or ccTLDs, and implementing correct hreflang tags to ensure search engines understand language variations. The skill is designed to help teams avoid common pitfalls such as broken canonical tags or poor user experiences caused by hardcoded date and currency formats.
When an agent loads this skill, it can produce a comprehensive internationalization plan. This plan includes a prioritized locale list, a chosen content structure—whether mirror, subset, or local—and a detailed translation workflow involving tools like a translation management system or spreadsheets. It also covers locale-aware UX design, such as handling right-to-left layouts for languages like Arabic or Hebrew and ensuring language switchers function correctly across different user sessions.
What an agent can do with it
- 1Design a URL structureDecide whether to use subfolders, subdomains, or ccTLDs for a new multi-region site rollout.
- 2Implement SEO language tagsCreate a plan for hreflang and canonical tags to ensure search engines index translated pages correctly.
- 3Establish translation workflowsOrganize how content moves from source authoring through review and localization to final publishing.
- 4Optimize locale-aware user interfacesConfigure how a site handles different currency, date, and number formats for specific regions.
- 5Audit existing internationalizationIdentify why an international rollout is underperforming or why translations are becoming stale.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the internationalization skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the internationalization skill in Plugin
/plugin marketplace add rampstackco/claude-skills /plugin install rampstack-skills@rampstack
Install the internationalization skill in Claude Code
~/.claude/skills/internationalization/SKILL.md
$ npx degit rampstackco/claude-skills/skills/internationalization ~/.claude/skills/internationalizationInstall the internationalization skill in Claude Code (project)
.claude/skills/internationalization/SKILL.md
$ npx degit rampstackco/claude-skills/skills/internationalization .claude/skills/internationalizationInstall the internationalization skill in Codex
~/.agents/skills/internationalization/SKILL.md
$ npx degit rampstackco/claude-skills/skills/internationalization ~/.agents/skills/internationalizationInstall the internationalization skill in Gemini CLI
~/.gemini/skills/internationalization/SKILL.md
$ npx degit rampstackco/claude-skills/skills/internationalization ~/.gemini/skills/internationalizationInstall the internationalization skill in Claude.ai
npx degit rampstackco/claude-skills/skills/internationalization internationalization && zip -r internationalization.zip internationalization # claude.ai → Customize → Skills → + → Create skill → Upload a skill → internationalization.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablerampstackco/claude-skills/skills/internationalization is public and reachablegithub.com/rampstackco/claude-skills/tree/HEAD/skills/intern ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-08github.com/rampstackco/claude-skills/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/rampstackco/claude-skills/blob/HEAD/skills/intern ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/rampstackco/claude-skills/blob/HEAD/skills/intern ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 279 linesgithub.com/rampstackco/claude-skills/blob/HEAD/skills/intern ↗Pass
SKILL.md
View on GitHubInternationalization
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.
<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-defaultis 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:
- Source content authored in the source language
- Translation requested through a TMS (translation management system) or spreadsheet
- Translation produced with translation memory (avoids retranslating reused phrases)
- Review by a second translator or in-region staff
- Localization beyond translation (currency, units, examples, cultural references)
- Publishing in the destination locale
- Update propagation when source content changes
The TMS pays off above ~10K words of total content. Below that, spreadsheets and disciplined naming are fine.
Update propagation is the hardest part. Source content changes. Translations go stale. Without a process, you end up with locales drifting from the source.
Layer 5: Locale-aware UX
Beyond translation, the experience must adapt.
Currency: display in the local currency where applicable. EUR for European locales, JPY for Japanese, etc. Don't show USD to French users for a French-locale page.
Numbers: thousand separators and decimals differ. 1,000.50 in en-US is 1.000,50 in de-DE.
Dates and times: format and order vary. MM/DD/YYYY in en-US, DD/MM/YYYY in en-GB, YYYY-MM-DD (ISO) is universal but unfamiliar to many.
Names and addresses: field order and required components differ. Country-aware address forms.
Phone numbers: E.164 international format universally; display formatting per locale.
Units: metric vs imperial. Most of the world is metric; the US is imperial. Some products serve both.
Right-to-left (RTL) languages: Arabic, Hebrew, Persian, Urdu. Layout flips: navigation moves right, text aligns right, icons that imply direction may flip too. CSS logical properties (margin-inline-start instead of margin-left) make this manageable.
Language switcher: prominent but not intrusive. Show locale names in their own language ("Deutsch" not "German"). Persist the choice. Don't auto-redirect based on browser language without offering a way back.
Cultural sensitivity: colors, imagery, examples, references that don't translate. Avoid hand gestures in product imagery. Avoid country-specific references unless localized.
Workflow
Step 1: Decide which locales
Don't add languages just because you can. Each locale has ongoing maintenance cost.
- Audience research: where are visitors and prospects?
- Business priority: which markets are growth targets?
- Content readiness: do you have the resources to maintain it?
- Legal: do regulations require localization (GDPR, accessibility laws)?
Step 2: Pick URL structure
Subfolder for most. Document the choice and rationale.
Step 3: Pick content structure
Mirror, subset, or local. Be honest about what's sustainable.
Step 4: Set up hreflang and canonicals
Implement before launching the second locale, even if it's just one extra page.
Step 5: Set up translation workflow
Pick a TMS or spreadsheet system. Document the workflow. Designate translators and reviewers.
Step 6: Localize beyond translation
For each locale:
- Currency, numbers, dates, units
- Locale-specific images if needed
- Address forms
- Customer service hours and contact
Step 7: Implement language switcher
- Prominent in the header or footer
- Shows the current locale clearly
- Lists all available locales in their own language
- Persists the choice (cookie or local storage)
- Doesn't auto-redirect based on browser; suggests instead
Step 8: Test
- Each locale renders correctly
- hreflang links are valid (use a checker)
- Canonicals are self-referential per page
- Currency and dates are correct
- RTL layout is correct (for RTL locales)
- Language switcher works and persists
- Search-engine perspective: each locale is crawlable and indexable
Step 9: Launch and monitor
Per locale:
- Indexing rate
- Traffic from intended geographies
- Engagement metrics in the locale
- Translation freshness (when did source content change without translation update?)
Step 10: Maintain
- Translation update cadence (when source changes, when translations follow)
- Quarterly review of locale performance
- Sunset locales that aren't viable (better than maintaining a dead locale poorly)
Failure patterns
Auto-redirect based on browser language. User is in Germany, prefers English. Site forces German. Frustrating. Suggest, don't redirect.
Single canonical to default language. Search engines can't index the translations. Self-canonical per page.
Reciprocal hreflang missing. German page lists English as its translation, English page doesn't list German. Search engines treat the relationship as unconfirmed.
hreflang language without region when region matters. hreflang="es" is fine if there's one Spanish version. If you have es-ES (Spain) and es-MX (Mexico), use both with regions.
Auto-translated content treated as final. Machine translation is an acceptable starting point. Human review is necessary for any user-facing content.
Currency baked into copy. "$99/month" in body text breaks for European users. Use templated currency that adapts.
Hardcoded date formats. "January 5, 2024" in code. Doesn't adapt. Use a date formatting library that respects locale.
Field labels left in source language. Translated body, untranslated form labels. Inconsistent. Translate UI strings as part of localization.
Untranslated error messages. User submits a form, gets an error in English on a French page. Frustrating. Translate UI states.
Untranslated emails. Site is in French; transactional emails are English. Translate emails to match.
Forgotten locales in CMS. Editors forget to update one locale. Drift. Use a TMS or workflow that surfaces drift.
Locale switcher that doesn't work mid-flow. User is on the German checkout, switches to French, lands on French homepage. Try to land on the same page in the new locale.
RTL layouts that don't actually flip. Margin and padding hardcoded for LTR. Use CSS logical properties.
Sunset language without redirect. Discontinuing French; old French URLs 404. Redirect to the closest equivalent in another supported language.
Output format
An internationalization plan includes:
- Locale list: with priority and audience rationale
- URL structure: chosen pattern and reason
- Content structure: mirror, subset, or local
- hreflang plan: how it's implemented
- Translation workflow: sources, stages, tools
- Localization checklist: beyond translation (currency, dates, etc.)
- Language switcher design: position, behavior, persistence
- Test plan: what's verified per locale
- Maintenance plan: update cadence, drift detection
Reference files
references/locale-checklist.md: Per-locale checklist of everything that needs to adapt beyond translation, organized by category (URL, content, UX, format, legal).
Files in this skill
3internationalization skill questions
How do I install the internationalization skill in Claude Code?
Run npx degit rampstackco/claude-skills/skills/internationalization ~/.claude/skills/internationalization. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the internationalization skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
What is the best URL structure for most websites?
For most sites, the subfolder pattern (e.g., example.com/de/) is the default as it unifies SEO equity and is the simplest to manage.
Should I auto-redirect users based on their browser language?
No, auto-redirecting can be frustrating if a user prefers a different language than their location suggests. It is better to suggest a language via a switcher rather than forcing a redirect.