i18n-expert

SKILL.md

I18n Expert

Overview

Deliver a complete i18n setup + audit pass: configure the i18n framework, replace user-facing strings with keys, ensure locale parity, and validate pluralization/formatting for en-US and zh-CN.

Core Capabilities

Library selection and setup (React, Next.js, Vue).

Key architecture and locale file organization.

Translation generation and quality strategy (AI, professional, manual).

Routing and language detection/switching.

SEO and metadata localization (when applicable).

RTL support (only if RTL locales are in scope).

Scope Inputs (ask if unclear)

Framework and routing style.

Existing i18n state (none, partial, legacy).

Target locales (default: en-US + zh-CN).

Translation quality needs (AI vs professional vs manual).

Locale formats in use (JSON, YAML, PO, XLIFF).

Formality/cultural requirements (if any).

Workflow (Audit -> Fix -> Validate)

Confirm scope and locale targets

Identify the i18n framework and locale locations.

Confirm locales; default to en-US + zh-CN when specified.

Setup i18n baseline (if missing)

Choose a framework-appropriate library (e.g., React: react-i18next; Next.js: next-intl; Vue: vue-i18n).

Install packages and create the i18n entry/config file.

Wire the provider at the app root and load locale resources.

Add a language switcher and persistence (route/param/localStorage) as appropriate.

Establish locale file layout and key namespaces.

If routing is locale-aware, define the locale segment strategy early (subpath, subdomain, query param).

If metadata is user-facing, include translation for titles/descriptions.

Audit key usage and locale parity

Run:
python scripts/i18n_audit.py --src <src-root> --locale <path/to/en-US.json> --locale <path/to/zh-CN.json>

Treat missing keys/parity gaps as blockers.

Manually verify dynamic keys (t(var)).

Find raw user-facing strings

Search:
rg -n --glob '<src>/**/*.{ts,tsx,js,jsx}' "<[^>]+>[^<{]*[A-Za-z][^<{]*<"
rg -n --glob '<src>/**/*.{ts,tsx,js,jsx}' "aria-label=\"[^\"]+\"|title=\"[^\"]+\"|placeholder=\"[^\"]+\""

Localize accessibility labels.

Replace strings with keys

Use t('namespace.key') for UI text.

For plurals use t('key', { count }) + _one/_other keys.

Use Intl/app formatters for time/date/number.

Localize error handling (critical)

Map error codes to localized keys; show localized UI only.

Log raw error details only.

Provide localized fallback for unknown codes.

Update locale files

Add missing keys in both locales.

Keep placeholders consistent; avoid renames unless requested.

Generate translations using the agreed method; preserve placeholders and plural rules.

Validate

Re-run the audit until missing/parity issues are zero.

Validate JSON (e.g., python -m json.tool <file>).

Update tests asserting visible text.

Guardrails

Never expose raw error.message to UI; show localized strings only.

Do not add extra locales unless explicitly requested.

Prefer structured namespaces (e.g., errors.*, buttons.*, workspace.*).

Keep translations concise and consistent.

Some technical/brand terms should remain untranslated (e.g., product name, API, MCP, Bash).

Deliverables (expected outputs)

i18n config/provider wiring.

Locale files for each target language.

Replaced UI strings with stable keys.

Language switcher and persistence (if applicable).

Updated tests for visible text.

Architecture Guidance (keep concise)

Key structure: prefer nested namespaces by area (e.g., common.buttons.save, pricing.tier.pro).

File layout: one file per locale or per-locale namespaces; keep keys in sync across locales.

Placeholders: preserve {name}/{{name}} exactly; validate plurals by locale rules.

Formatting: use Intl/app helpers for date, time, number, and list formatting.

SEO/metadata: localize titles and descriptions if the app exposes them.

RTL: only needed for RTL locales; use logical CSS properties and test layout.

Non-web surfaces (Electron main-process dialogs, CLI prompts, native menus) need localization too.

Performance Notes (short)

Lazy-load locale bundles when the app supports it.

Split large locale files by namespace.

Failure Modes (watchlist)

Missing translations: fall back to default locale and log warnings.

RTL layout issues: verify logical CSS and test pages.

SEO missing: ensure alternates and metadata are localized when applicable.

Validation Checklist (short)

No missing keys and no raw UI strings.

Locale switching works and persists.

Plurals and formatting verified in both locales.

Fallback locale configured.

Resources

scripts/

scripts/i18n_audit.py: Extracts t('key') usage and compares against locale JSON files.