Agent Skills: Software Localisation

Software Localisation

Use this skill for production web-app i18n and l10n: library choice, message catalogs, ICU usage, locale routing, translation workflow, RTL, and release gates. The goal is not just translated strings. The goal is locale-safe product behavior.

When to Use This Skill

• setting up or debugging i18n in React, Vue, Angular, or Next.js
• choosing libraries and catalog strategy
• implementing ICU pluralisation, formatting, and locale detection
• adding RTL support
• configuring extraction, translation workflow, or TMS integration
• fixing missing translations, mixed-language regressions, or bad locale fallback behavior
• delivering backend-generated prose (AI summaries, narratives) to localized web or native clients

Route Elsewhere

• general frontend architecture -> software-frontend
• international SEO and hreflang -> marketing-seo
• cross-cultural UX and market adaptation -> software-ui-ux-design or marketing-geo-localization
• general WCAG/ARIA compliance and European Accessibility Act (EAA) readiness -> software-accessibility; this skill only covers the i18n-specific slice (lang/dir propagation, script-aware line height, IME) in references/accessibility-i18n.md

When Not to Use This Skill

• The product has one locale and no committed plan to add more — don't pre-build ICU catalogs, TMS integration, or locale routing "just in case." Ship plain strings and revisit when a second locale is real.
• The ask is "translate this text" with no code, catalog, or product surface involved — that's a translation task, not a localisation-engineering task; do it directly.
• The ask is about international SEO structure (hreflang, ccTLD vs subfolder) with no i18n implementation involved -> route to marketing-seo instead.

Native Mobile Boundary

This skill owns strings, plurals, catalogs, and the translation pipeline for native apps as well as web, including backend-generated prose and catalog key/value parity: see references/backend-generated-content-i18n.md. Framework setup here is web-first; the platform APIs belong to software-ios-native, software-android-native, or software-mobile. Anchors to check there:

• iOS: String Catalogs (Localizable.xcstrings); plurals via the editor's "Vary by Plural", which adds each language's CLDR plural forms.
• Android: per-app language preference (Android 13 / API 33+) via AppCompatDelegate.setApplicationLocales(LocaleListCompat.forLanguageTags(...)) (backward-compatible) or LocaleManager; declare locales with android:localeConfig, or androidResources { generateLocaleConfig = true } (AGP 8.1+).

Workflow

1. Confirm framework, locale count, route strategy, and translation workflow.
2. Choose the library and catalog model.
3. Define explicit-route resolution separately from first-entry locale negotiation and persistence.
4. Implement ICU or equivalent message formatting correctly.
5. Add extraction, missing-key, and stale-translation controls (missing key detection); for LLM/MT drafts, enforce the ICU-AST, glossary, quality-estimation, and reviewer gates in references/translation-workflows.md.
6. Add RTL and visual regression coverage where needed; see references/testing-i18n.md for pseudo-localisation, RTL automation, and pluralisation edge-case test patterns.
7. Block release on mixed-language or unsafe fallback behavior for indexable or customer-visible routes.

Quick Reference

| Situation | Library | Why | |---|---|---| | React / TypeScript, general flexibility | i18next + react-i18next | Selector typing when enabled; plugin integration | | ICU-first catalogs, FormatJS tooling already in use | react-intl | ICU catalogs with FormatJS extract/compile | | Next.js App Router | next-intl | Built for RSC + App Router; configured locale routing | | Vue | vue-i18n | Framework-native; Vue tooling integration | | Angular | @angular/localize | Build-time extraction and AOT compilation | | Smaller bundle budget | Lingui | Macro extraction; measure the shipped bundle | | Team explicitly wants generated type wrappers | typesafe-i18n | Full key-type safety; high maintenance model |

Do not choose by popularity alone. Choose by routing model, extraction needs, ICU expectations, and team maintenance habits. For setup steps per framework, see references/framework-guides.md.

ICU MessageFormat 2 (MF2): Not Yet a Default Choice

MF2 is standardized at the syntax level in Unicode's LDML spec (Stable since CLDR/LDML 47, March 2025), which makes it tempting to treat as "the new ICU." Do not migrate production catalogs to it until the toolchain catches up: check whether ICU's own implementations have left draft/technology-preview status, whether your library (react-intl/FormatJS, i18next, vue-i18n, Lingui) ships a production MF2 path, and whether your TMS round-trips it. Keep using MessageFormat 1 / ICU syntax (documented in references/icu-message-format.md) and re-check adoption status before recommending a switch — this is a common "the spec is final, so it must be safe to use" misdiagnosis.

Core Rules

Encoding and content model

• use UTF-8 end to end
• never concatenate translatable strings
• use interpolation and ICU plural or select rules instead of ad hoc formatting

Locale routing and fallback

• an explicit locale in a valid URL or deep link wins for that request; preserve it through navigation and canonical metadata (see references/locale-handling.md for date/number/currency detection specifics)
• when no explicit locale is present, negotiate from authenticated preference, persisted choice, supported Accept-Language, then default locale
• a stored preference may redirect an unlocalized entry route, but must not silently rewrite a shared explicit-locale URL
• always define a fallback locale
• never silently fall back to English on indexable non-English routes
• metadata, breadcrumbs, JSON-LD, and visible copy must stay in the same locale

Translation workflow

• extract keys, do not hand-copy them
• keep namespace structure stable
• add translator context, glossary rules, and review gates; see references/translation-workflows.md for extraction/TMS/CI pipeline patterns and references/content-management-patterns.md for TM, glossary, and cost-at-scale patterns
• hardcoded string detection and missing-key checks should run in CI

RTL and accessibility

• use CSS logical properties
• set dir="rtl" where required
• test with real RTL content; see references/rtl-support.md for Arabic/Hebrew/Farsi-specific patterns
• verify BiDi handling, icons, and screen-reader behavior across locales

Production Gates

| Gate | Failure condition | Remediation | |---|---|---| | Mixed-language output | Any locale-routed page renders keys from a different locale | Missing-key CI check catches before merge | | Missing-key bleed | Core UX or marketing route shows a key ID or raw fallback string | Extraction + catalog diff in CI pipeline | | Machine translation on release path | MT output inserted without glossary, tone, or reviewer gate | Add human review step for all customer-visible locales | | Locale switch drops state or breaks navigation | User changes locale and loses cart, form, or route state | Centralize locale state; separate from route/cookie | | RTL launched without visual validation | Arabic/Hebrew/Farsi layout broken on launch | Require visual pass on one RTL locale before release | | Localized accessibility regression | Locale changes break language/direction markup, script rendering, or text input | Test the i18n accessibility slice in references/accessibility-i18n.md; route legal applicability to the accessibility owner |

Known Traps

| Trap | Prevention | |---|---| | Keys drift between extraction, TMS, and runtime — fallback "works" but locale is broken | Run missing-key checks in CI; diff extraction output against TMS catalog before release | | Visible strings translated, but validation messages / metadata / emails / JSON-LD left in English | Enumerate all locale surfaces (UI, email, SEO, legal) at project start; treat each as a separate test gate | | String concatenation for grammar-sensitive or gendered copy | Use ICU {count, plural, ...} / {gender, select, ...} (or the library's own plural syntax, e.g. vue-i18n pipe plurals); never "Hello " + name | | Only Latin-script locales tested | Require one long-string locale (de/ru) and one non-Latin (ja/ar) before "complete" | | Locale persisted separately in route, cookie, and client state with no precedence rule | Separate resolution rules: explicit URL/deep-link locale for the request; otherwise authenticated preference > persisted choice > supported Accept-Language > default | | Machine translation shipped without glossary or review | Require glossary, tone rules, and human review gate for all customer-visible content | | Plural category count assumed from memory (e.g. "French is just one/other like English") | CLDR revises per-language category counts over time (French now has one, many, other); verify against the current CLDR plural rules chart, don't hardcode from a prior project | | Translated content rendered as raw HTML (v-html, dangerouslySetInnerHTML, ICU HTML tags) with no CSP/Trusted Types | Real XSS advisories exist for this exact pattern in both vue-i18n (CVE-2025-53892) and Angular's i18n pipeline (CVE-2026-27970) — treat translation-file write access as privileged and pin patched library versions |

Common Anti-Patterns

| Anti-pattern | Correct approach | |---|---| | English as silent fallback on locale-routed pages | Fail visibly in CI or preview when a key is missing in a non-default locale | | Business logic encoded in translation keys | Keys represent UI text; business logic belongs in code | | Translations split by developer convenience | Split by stable product domain and runtime loading boundary | | CSS directional properties (left, right) patched per-view for RTL | Use CSS logical properties (inline-start, inline-end) from the start | | Each product surface (marketing, support, product) runs separate locale logic | Centralize fallback, formatting, and detection in one shared locale layer |

Ops Runbook

For large locale catalogs or mixed-language incidents:

• diff keys first
• translation pass second
• treat marketing and SEO locale gaps as release blockers
• chunk large locale files instead of reading them in one pass

Use references/ops-runbook.md for the detailed triage procedure.

Navigation

Core references

• references/framework-guides.md
• references/icu-message-format.md
• references/translation-workflows.md
• references/rtl-support.md
• references/locale-handling.md
• references/testing-i18n.md
• references/accessibility-i18n.md
• references/content-management-patterns.md
• references/ops-runbook.md
• references/backend-generated-content-i18n.md — backend-generated prose for localized clients (generate-in-locale vs translate-after-cache), locale contract, native catalog parity

Templates and data

• assets/react-i18next-setup.md
• assets/vue-i18n-setup.md
• assets/nextjs-i18n-setup.md
• data/sources.json

Maintenance

• python3 scripts/check_urls.py
• python3 scripts/check_examples.py

Related Skills

• software-frontend
• marketing-seo
• software-accessibility

Learnings Loop

When prior decisions or pitfalls are relevant, consult learnings.consolidated.md if present; use learnings.md only for needed history or as the available fallback. Otherwise skip both.

After applying it, if you encountered a pattern worth remembering, a mistake worth preventing, or a domain fact that surprised you, append one dated bullet to learnings.md via agents-skills-feedback-loop/scripts/append_learning.py. Do not modify SKILL.md itself.