/localize

name: localize
type: workflow
description: "Generates or updates i18n localization files, translation keys, and locale configurations. Use when adding a new language, updating translation strings, or when the user mentions localization, i18n, translation, or l10n."
argument-hint: "[scan|extract|validate|status]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Bash
effort: 1
when_to_use: "When scanning, extracting, or validating localization strings, or checking for hardcoded text in the codebase"

When this skill is invoked:

1. **Parse the subcommand** from the argument:

• `scan` — Scan for localization issues (hardcoded strings, missing keys)
• `extract` — Extract new strings and generate/update string tables
• `validate` — Validate existing translations for completeness and format
• `status` — Report overall localization status

2. **For `scan`**:

• Search `src/` for hardcoded user-facing strings:
• String literals in UI code that are not wrapped in a localization function
• Concatenated strings that should be parameterized
• Strings with positional placeholders (`%s`, `%d`) instead of named ones (`{playerName}`)
• Search for localization anti-patterns:
• Date/time formatting not using locale-aware functions
• Number formatting without locale awareness
• Text embedded in images or textures (flag asset files)
• Strings that assume left-to-right text direction
• Report all findings with file paths and line numbers

3. **For `extract`**:

• Scan all source files for localized string references
• Compare against the existing string table (if any) in `assets/data/`
• Generate new entries for strings that don't have keys yet
• Suggest key names following the convention: `[category].[subcategory].[description]`
• Output a diff of new strings to add to the string table

4. **For `validate`**:

• Read all string table files in `assets/data/`
• Check each entry for:
• Missing translations (key exists but no translation for a locale)
• Placeholder mismatches (source has `{name}` but translation is missing it)
• String length violations (exceeds character limits for UI elements)
• Orphaned keys (translation exists but nothing references the key in code)
• Report validation results grouped by locale and severity

5. **For `status`**:

• Count total localizable strings
• Per locale: count translated, untranslated, and stale (source changed since translation)
• Generate a coverage matrix:

   ## Localization Status
   Generated: [Date]

   | Locale | Total | Translated | Missing | Stale | Coverage |
   |--------|-------|-----------|---------|-------|----------|
   | en (source) | [N] | [N] | 0 | 0 | 100% |
   | [locale] | [N] | [N] | [N] | [N] | [X]% |

   ### Issues
   - [N] hardcoded strings found in source code
   - [N] strings exceeding character limits
   - [N] placeholder mismatches
   - [N] orphaned keys (can be cleaned up)

Rules

• English (en) is always the source locale
• Every string table entry must include a translator comment explaining context
• Never modify translation files directly — generate diffs for review
• Character limits must be defined per-UI-element and enforced automatically
• Right-to-left (RTL) language support should be considered from the start, not bolted on later