i18n expert
- Repo stars 0
- Author updated Aug 24, 2026, 07:33 AM
- Author repo claude-code-skills
- Domain
- Other
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @daymade · no license declared
- Token usage
- Lean
- Setup complexity
- Plug-and-play
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- Python
- Detected file/system behavior
-
- Read-only
- Write / modify
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# 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.
# 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.
2) 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.
3) 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)`).
4) 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.
5) 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.
6) 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.
7) 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.
8) 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.
Sections and files
Listed in source order.
sections -> Overview → Core Capabilities → Scope Inputs (ask if unclear) → Workflow (Audit -> Fix -> Validate) → Guardrails → Deliverables (expected outputs)
terms -> - Library selection and setup (React, Next.js, Vue). · - Framework and routing style. · 1) Confirm scope and locale targets - Identify the i18n framework and locale locations. · 2) Setup i18n baseline (if missing) - Choose a framework-appropriate library (e.g., React: react-i18next; Next.js: next-intl; Vue: vue-i18n). · 5) Replace strings with keys - Use t('namespace.key') for UI text. · 6) Localize error handling (critical) - Map error codes to localized keys; show localized UI only. · 7) Update locale files - Add missing keys in both locales. · 8) Validate - Re-run the audit until missing/parity issues are zero.
files/cmd -> t(var) · t('namespace.key') · t('key', { count }) · _one/_other · python -m json.tool <file> · error.message · errors.* · buttons.*
body sha256 -> c2c54157aabd
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).
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).
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).
Guardrails
Never expose raw
error.messageto 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).