Internationalization (i18n)

Make a codebase correct outside a single locale. This skill audits and implements internationalization across nine domains documented in reference modules under references/.

Modes

Declare the active operating mode before executing any steps:

• Implementation mode (default): Ingest scope, load domain references, audit patterns, and implement localization changes. Run Steps 1 through 5 sequentially.
• Audit mode (/i18n audit only): Scan codebase for unlocalized copy, date formatters, and physical CSS rules. Run Steps 1 through 3 only, emit .agents/state/i18n/audit-report.md, and halt without modifying files.

Scope contract

The user may narrow the work by naming aspects, languages, or both. Parse the request before modifying files:

Rules for narrowed requests:

1. A narrowed language set narrows configuration, not code correctness. If only en and es are requested, use logical CSS properties, locale-aware formatting APIs, and ICU messages so future locales require only configuration changes.
2. A narrowed domain set does not excuse breaking sibling domains. Note out-of-scope defects in findings without fixing them unless user expands scope.
3. When target language set is ambiguous, ask user before implementing.

Reference quick routing

Workflow

Step 1. Stack and inventory reconnaissance

Audit the repository to detect existing i18n tooling before adding dependencies:

head -n 60 package.json pyproject.toml composer.json Gemfile go.mod 2>/dev/null
grep -rIl --exclude-dir={node_modules,.git,dist,build,vendor} -E "i18next|react-intl|vue-i18n|next-intl|formatjs|gettext|babel|lingui|MessageFormat" . | head -n 30
find . -path ./node_modules -prune -o \( -name "*.po" -o -name "*.xliff" -o -name "*.arb" -o -name "*.ftl" -o -name "messages*.json" -o -name "locales" -o -name "i18n" \) -print 2>/dev/null | head -n 30

Record runtime capabilities, existing catalog locations, translation formats, and user locale persistence sources. Extend existing libraries instead of introducing competing frameworks.

Completion criterion. .agents/state/i18n/scope.json exists on disk with detected_libraries, catalog_paths, in_scope_languages, and mode.

Step 2. Progressive disclosure and domain module loading

Consult only reference modules relevant to scoped domains:

Completion criterion. Session context contains all relevant domain reference files based on user scope.

Step 3. Audit and severity classification

Scan for locale-hardcoded patterns and catalog findings:

grep -rn --exclude-dir={node_modules,.git,dist,build,vendor} -E "toLocaleDateString\(\)|toLocaleString\(\)|new Date\(.*\)\.getDate\(\)" . | head -n 100
grep -rn --exclude-dir={node_modules,.git,dist,build,vendor} -E "\.toUpperCase\(\)|\.toLowerCase\(\)" . | head -n 100
grep -rn --exclude-dir={node_modules,.git,dist,build,vendor} -E "=== *1|=== *0|count *[<>=]+ *1|\$\{count\}" . | head -n 100
grep -rn --exclude-dir={node_modules,.git,dist,build,vendor} -E "margin-left|margin-right|padding-left|padding-right|text-align:\s*(left|right)|left:|right:" . | head -n 100
grep -rn --exclude-dir={node_modules,.git,dist,build,vendor} -E "\.sort\(\)|ORDER BY" . | head -n 100

Classify each finding by impact:

Completion criterion. .agents/state/i18n/audit-report.md exists on disk with file locations, line numbers, defect categories, and planned remediation.

When operating in Audit mode, output findings table and halt. Do not proceed to Step 4.

Step 4. Ordered implementation

Execute changes in strict architectural sequence:

1. Locale model. Define how locales are negotiated, stored, and resolved across boundaries.
2. Catalog structure. Establish message files, keying conventions, and interpolation tokens.
3. String extraction. Replace hardcoded copy with catalog keys and named parameters.
4. Formatting. Replace ad-hoc date and number formatters with standard platform APIs or library formatters.
5. Plurals and grammar. Convert count-dependent logic to ICU plural messages with CLDR categories.
6. Layout and BiDi. Switch physical CSS properties to logical equivalents, and set dir attributes on root containers.
7. Collation. Replace code-unit comparisons with locale-aware collator calls.
8. Testing infrastructure. Add pseudolocale pipelines, lint rules, and matrix test fixtures.

Completion criterion. Code modifications apply in sequence matching repository conventions without unused abstractions.

Step 5. Verification

Verify work against concrete criteria:

1. Run project build and automated test commands. Detect package manager and test runner from lockfiles:

Record the resolved command in .agents/state/i18n/verification-commands.txt before running. 2. Audited views render all in-scope locales without falling back to default language keys. 3. User-facing paths contain zero raw toLocaleDateString() or new Date().toString() calls without explicit locale options. 4. Numeric conditionals like count === 1 are replaced with ICU plural syntax. 5. String comparisons use Intl.Collator or case folding rather than raw toLowerCase(). 6. Layouts employ CSS logical properties (margin-inline-start, padding-inline-end). 7. Pseudolocale tests show zero unextracted raw strings and zero truncated containers.

Completion criterion. Project build and test commands exit with code 0 and raw output is recorded in .agents/state/i18n/verification.txt with zero unresolved audit items.

Anti-patterns

Boundary isolation

Apply internationalization changes strictly to user-facing strings, formatting calls, and layout directives:

• Keep database column names, internal event payloads, API route identifiers, and configuration keys in their original canonical English or system format.
• Protect code syntax, CLI commands, and test assertion primitives from translation or localized casing alterations.

Quick audit checklist

Review this table before completing internationalization changes: