Skill · Internationalization
Internationalization.
Add languages and regions that work for users, search engines, and the team.
Add languages and regions in a way that works for users, search engines, and the team maintaining the content. Internationalization touches everything, across five layers: URL structure, content structure, hreflang and canonicals, translation workflow, and locale-aware UX.
The hard part is not the first translation but keeping locales from drifting stale. Add languages for a business reason, because each one carries ongoing maintenance cost.
Audience: engineering and content teams adding locales, choosing a language URL structure, implementing hreflang, or fixing a stalled internationalization rollout.
The framework
Five layers, each with its own decisions.
Internationalization touches everything. These five layers each carry their own decisions, from the URL down to the date format.
- 01URL structure: subfolder by default (example.com/de/, SEO equity unified, simplest to manage). Subdomain or ccTLD only for a legal, infrastructure, or brand reason; avoid the URL-parameter pattern.
- 02Content structure: mirror (every page in every locale), subset (some content per locale), or local (independent per locale). Be honest about what is sustainable.
- 03hreflang and canonicals: every page lists every translated equivalent including itself, the relationships reciprocate, x-default covers unspecified regions, and each page self-canonicals.
- 04Translation workflow: author, request, translate with memory, review, localize, publish, and propagate updates, with a TMS above about 10,000 words. Keeping translations in sync as the source changes is where rollouts stall.
- 05Locale-aware UX: currency, numbers, dates, units, addresses, RTL layout via CSS logical properties, and a language switcher that names locales in their own language and persists the choice.
Locale-aware UX
Six things that adapt beyond the words.
Translation is only part of it; the experience itself has to adapt to the locale. These are the parts teams most often leave in the source language.
01
Currency
Display in the local currency, never USD on a French-locale page. Templated so it adapts, not baked into the body copy.
02
Numbers and dates
1,000.50 in en-US is 1.000,50 in de-DE, and date order differs by locale. Use a locale-aware formatting library, not hardcoded formats.
03
Units
Metric versus imperial. Most of the world is metric; some products need to serve both.
04
RTL layout
Arabic, Hebrew, Persian, and Urdu flip the layout. CSS logical properties like margin-inline-start make this manageable.
05
Language switcher
Prominent but not intrusive, locale names in their own language, persists the choice, and suggests rather than auto-redirecting on browser language.
06
UI strings
Form labels, error messages, and transactional emails get translated too, beyond the body content.
What keeps it from drifting
hreflang rules, no auto-redirect, fight the drift.
hreflang and canonicals are where internationalization SEO is won or lost. Every page lists every translated equivalent including itself, the relationships reciprocate (the German page names the English version and the English page names the German), x-default covers users in unspecified regions, and each page self-canonicals rather than pointing to the default language, or search engines will not index the translations.
Do not auto-redirect on browser language. A user in Germany who prefers English should not be forced into German, so suggest the locale, offer a clear way back, and persist the choice. Machine translation is an acceptable starting point, but any user-facing content needs human review, and the localization reaches past the body copy to currency, dates, units, form labels, error messages, and transactional emails.
Update propagation is the hardest part. Source content changes and the translations drift stale, so the workflow has to surface that drift, a translation management system pays off above roughly 10,000 words, and a locale that cannot be maintained is better sunset (with redirects) than maintained poorly. Add languages for a business reason, because each one carries an ongoing maintenance cost.
Reference files
The reference that goes alongside the SKILL.md.
references/locale-checklist.md
A per-locale checklist of everything that adapts beyond translation, organized by category: URL, content, UX, format, and legal.
Bridges to other skills
The skills i18n touches.
Internationalization spans structure, SEO, and content. These cover the domain choice, the technical hreflang layer, and the content it localizes.
The domain choice
domain-strategyNon-language domain decisions live in domain strategy. The language URL choice (ccTLD, subdomain, subfolder) is made here, against the portfolio that skill manages.
The technical layer
seo-technicalhreflang and canonicals are part of the technical SEO foundation. This skill plans the locale structure; technical SEO verifies the rendering and indexing of it.
What to localize
content-strategyLocale-independent content planning is a content-strategy job. This skill decides how that content adapts per locale, not what content the program produces.
The translated copy
content-and-copyProducing marketing copy, including in a target language, is a writing task. This skill owns the structure, hreflang, and workflow around the words.
Open source under MIT
Read the SKILL.md on GitHub.
The skill source lives in the rampstackco/claude-skills repository alongside dozens of other skills covering the full lifecycle of brand and product work. This page is a structured overview; the SKILL.md is the source. MIT licensed.
Frequently asked questions.
- What URL structure should I use for locales?
- Subfolder by default (example.com/de/), which keeps SEO equity unified and is the simplest to manage. Use a subdomain (de.example.com) or a ccTLD (example.de) only for a specific legal, infrastructure, or brand reason, and avoid the URL-parameter pattern (example.com?lang=de), which is a weak SEO signal. Within the chosen pattern, decide whether you need language only (/de/) or language plus region (/de-de/, /de-at/, /de-ch/), and where the default locale lives.
- How do hreflang and canonicals work together?
- Every page lists every translated equivalent, including itself, and the relationships must reciprocate: if the German page names the English version, the English page must name the German one, or search engines treat the relationship as unconfirmed. Include an x-default for users in unspecified regions, and give each page a self-referential canonical. Do not canonical the German page to the English one, because search engines will then refuse to index the German page. hreflang can sit in the head, in HTTP headers, or in the sitemap, which is best for large sites.
- Should I auto-redirect by browser language?
- No. A user in Germany who prefers English should not be forced into German, which is a top failure mode. Suggest the locale instead, offer a clear way back, and persist the choice. The language switcher should be prominent but not intrusive, list locales in their own language ('Deutsch', not 'German'), and try to land the user on the same page in the new locale rather than dumping them on the homepage when they switch mid-flow.
- Is machine translation good enough?
- As a starting point, yes; as the final product for user-facing content, no. AI-assisted translation plus human review is cheap, fast, and improving, but treating auto-translated content as final is a failure mode. And the translation has to be complete: body copy translated while form labels, error messages, and transactional emails stay in the source language is jarring and inconsistent, so localize the UI strings and emails as part of the work, alongside the page content.
- What is the hardest part of internationalization?
- Update propagation. Source content changes and the translations drift stale, so the workflow has to surface that drift, which is what a translation management system is for (it pays off above roughly 10,000 words of total content; below that, disciplined spreadsheets are fine). Add locales for a real business reason, because each carries ongoing maintenance cost, and a locale that cannot be kept current is better sunset, with redirects to the closest supported language, than maintained poorly.