i18n-localization

i18n Localization

Use this skill to plan, review, or harden localization work across product UI, documentation, marketing pages, emails, and web/app routing surfaces.

Canonical Vocabulary

Term	Meaning
locale	Language plus optional regional conventions, such as en, en-US, or ar-EG
message catalog	Source of translated strings and message metadata
ICU message	Message format that models variables, plurals, selects, and ordinals safely
pseudo-locale	Test locale that expands and marks strings to reveal hardcoded text and layout clipping
RTL	Right-to-left layout direction for languages such as Arabic and Hebrew
fallback	Intentional behavior when a locale, key, or translation is missing

Dispatch

$ARGUMENTS	Mode	Output
Empty	Localization audit	Inspect the current surface, identify locale risks, and return a prioritized remediation plan.
App, route, feature, or file path	Implementation plan	Map the affected strings, routing, formatting, QA, and release checks for that scope.
Locale or market list	Locale readiness review	Verify language, region, formatting, routing, fallback, and translation handoff requirements.
Existing plan or diff	Review	Check for missed strings, unsafe concatenation, formatting bugs, catalog drift, RTL gaps, and missing tests.
Natural language outside localization	Redirect	Explain the scope boundary and route to the better skill.

When the user gives no arguments, start with a localization audit of the relevant repository or product surface. Do not ask for locale preferences until the codebase and user request leave a real decision unresolved.

Reference File Index

File	Read When
references/localization-checklist.md	Planning, implementing, reviewing, testing, or releasing localization work

Critical Rules

1. Treat localization as a product contract, not a translation pass. Cover routing, formatting, accessibility, search metadata, analytics labels, emails, and support surfaces when they are in scope.
2. Never concatenate translated fragments to build a sentence. Use full messages with variables, ICU/select/plural forms, or the framework's equivalent message format.
3. Keep user-visible strings out of business logic and shared constants unless the system already has a catalog abstraction for that layer.
4. Use locale-aware formatters for dates, times, numbers, currencies, lists, relative times, units, and names. Do not hand-roll formatting with string templates.
5. Separate language from region. en, en-US, and en-GB can imply different copy, dates, currency, measurement units, and legal content.
6. Define fallback behavior explicitly. Missing translations should fail visibly in development and degrade intentionally in production.
7. Include pseudo-locale checks for expansion, accenting, bracket markers, interpolation safety, and truncation.
8. Include RTL and bidirectional text checks when any Arabic, Hebrew, Persian, Urdu, or mixed-direction user content can appear.
9. Preserve stable message keys. Do not churn catalogs or invalidate translation memory unless the source message meaning changes.
10. Keep translators away from code syntax. Provide notes, screenshots, variable descriptions, character constraints, and product context.