i18n-helper

name	i18n-helper
description	Extract hardcoded strings into translation keys, generate locale files, find untranslated strings, and validate locale completeness. Use when the user asks to internationalize their app, add translations, extract strings, check for missing translations, or set up i18n.
version	1.0.0
tools	["Read","Write","Grep","Glob","Bash"]

i18n/Localization Helper

Extract hardcoded strings, generate locale files, and validate translation completeness across languages.

Workflow

1. Detect the i18n framework in use

   grep -E "i18next|react-intl|vue-i18n|next-intl|@formatjs" package.json 2>/dev/null
   

   Check for config files: i18n.ts, next.config.js with i18n key, src/locales/. If no framework found, recommend one and help set it up.

2. Discover existing locale files

   find . -maxdepth 4 \( -name "*.json" -o -name "*.yaml" \) -path "*/locale*" -o -path "*/i18n/*" -o -path "*/translations/*" | grep -v node_modules
   

   Parse each file, build key inventory per language. Note structure: flat vs nested keys.

3. Scan source code for hardcoded strings Find user-facing strings in JSX text, component props, toast/alert calls, page titles, form validation messages. Exclude: CSS classes, console.log, import paths, test strings, URLs.

4. Generate translation keys Naming convention: page.section.element

   "Welcome back"     → common.welcomeBack
   "Submit"           → common.buttons.submit
   "Email is required" → forms.validation.emailRequired
   

5. Extract and update source code Replace hardcoded strings with translation calls:

   // Before
   <h1>Welcome back</h1>
   
   // After (i18next)
   const { t } = useTranslation();
   <h1>{t("common.welcomeBack")}</h1>
   

6. Generate or update locale files Create JSON/YAML for each language. Non-primary languages get placeholders:

   { "common": { "welcomeBack": "[ES] Welcome back" } }
   

7. Validate locale completeness

   en.json:  142/142 keys (100%)
   es.json:  128/142 keys (90.1%) — 14 missing
   fr.json:  135/142 keys (95.1%) — 7 missing
   

8. Find unused translation keys Report keys in locale files never referenced in source code.

Rules

• Never modify non-primary locale files without user confirmation
• Preserve existing key structure and ordering
• Mark placeholder translations with [TODO] or [LANG] prefix
• Do not extract developer-facing strings (logs, error codes)
• Handle pluralization using the framework's syntax
• Handle interpolation: "Hello, {{name}}" not string concatenation
• Process one file at a time, show changes before applying
• Sort keys alphabetically within namespaces