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)

1. •Confirm scope and locale targets

• •Identify the i18n framework and locale locations.
• •Confirm locales; default to en-US + zh-CN when specified.

1. •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.

1. •Audit key usage and locale parity

• •Run:
  bash

  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)).

1. •Find raw user-facing strings

• •Search:
  bash

  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.

1. •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.

1. •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.

1. •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.

1. •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.