i18n

1. Pick the Mode

• Build mode — the task creates or changes UI or formatting code. Apply the rules as constraints while writing it. Mention a rule only when it changed a decision, in one line.
• Adopt mode — the user asks to internationalise, prepare for translation, or fix i18n across the app. Work through Step 4.

2. Detect the Platform

package.json

references/js.md

*.xcodeproj

Package.swift

references/apple.md

build.gradle(.kts)

references/android.md

next-intl

react-i18next

vue-i18n

FormatJS

references/js.md

3. Rules

rules/localisable-strings.md

rules/time-zones.md

rules/locale-formatting.md

rules/units.md

rules/text-and-layout.md

rules/deterministic-tests.md

4. Adopt Mode

1. Inventory — find hardcoded user-facing strings, hand-rolled date/number formats, string concatenation, fixed units, and

   left

   /

   right

   layout. Report the counts before editing
2. Set up the resource — one string catalog or message file in the platform's native format, English (or the project's development language) only
3. Fix in impact order — CRITICAL first. Change only what international correctness needs; keep the existing design and behaviour
4. Never change persisted data semantics (timestamp meaning, stored units) without an explicit migration the user has approved — propose it instead
5. Test — add the deterministic tests from

   rules/deterministic-tests.md

   ; build and run the suite, and report real results
6. Validate the UI — pseudolocalisation, the longest text expansion, RTL, and the largest text size, using the tools in the platform guide

Boundaries

• Accessibility labels must be localisable like any string; what they should say belongs to

  accessibility

  .
• User-generated content (names, notes, place names) is never translated, transliterated, or normalised unless the user asks.
• Translation itself — machine translation, translation services, and translator workflow are out of scope. Do not send app strings or user content to an external service.