localize

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys automation

Localization Pipeline

Localization is not just translation — it is the full process of making a game feel native in every language and region. Poor localization breaks immersion, confuses players, and blocks platform certification. This skill covers the complete pipeline from string extraction through cultural review, VO recording, RTL layout testing, and localization QA sign-off.

Modes:

• scan — Find hardcoded strings and localization anti-patterns (read-only)
• extract — Extract strings and generate translation-ready tables
• validate — Check translations for completeness, placeholders, and length
• status — Coverage matrix across all locales
• brief — Generate translator context briefing document for an external team
• cultural-review — Flag culturally sensitive content, symbols, colours, idioms
• vo-pipeline — Manage voice-over localization: scripts, recording specs, integration
• rtl-check — Validate RTL language layout, mirroring, and font support
• freeze — Enforce string freeze; lock source strings before translation begins
• qa — Run the full localization QA cycle before release

If no subcommand is provided, output usage and stop. Verdict: FAIL — missing required subcommand.

Every AskUserQuestion call follows .claude/docs/automation-modes.md (collaborative asks always · guided major-only · autonomous logs and proceeds; automation_always_ask categories always prompt).

Phase 2A: Scan Mode

Search the code root (resolve per .claude/docs/code-root-resolution.md) for hardcoded user-facing strings. If the code root is unresolved, report NOT ASSESSED — code root unresolved rather than zero hits. Zero hits from an unresolved root reads as "nothing to localize", which is the failure this guards:

• String literals in UI code not wrapped in a localization function (tr(), Tr(), NSLocalizedString, GetText, etc.)
• Concatenated strings that should be parameterized
• Strings with positional placeholders (%s, %d) instead of named ones ({playerName})
• Format strings that mix locale-sensitive data (numbers, dates, currencies) without locale-aware formatting

Search for localization anti-patterns:

• Date/time formatting not using locale-aware functions
• Number formatting without locale awareness (1,000 vs 1.000)
• Text embedded in images or textures (flag asset files in assets/)
• Strings that assume left-to-right text direction (positional layout, string assembly order)
• Gender/plurality assumptions baked into string logic (must use plural forms or gender tokens)
• Hardcoded punctuation (e.g. "You won!" — exclamation styles vary by locale)

Report all findings with file paths and line numbers. This mode is read-only — no files are written.

Phase 2B: Extract Mode

• Scan all source files for localized string references
• Compare against the existing string table in assets/data/strings/
• Generate new entries for strings not yet keyed
• Suggest key names following the convention: [category].[subcategory].[description]
  • Example: ui.hud.health_label, dialogue.npc.merchant.greeting, menu.main.play_button
• Each new entry must include a context field — a translator comment explaining:
  • Where it appears (which screen, which scene)
  • Maximum character length
  • Any placeholder meaning ({playerName} = the player's chosen display name)
  • Gender/plurality context if applicable

Output a diff of new strings to add to the string table.

Present the diff to the user. Ask: "May I write these new entries to assets/data/strings/strings-en.json?"

If yes, write only the diff (new entries), not a full replacement. Verdict: COMPLETE — strings extracted and written.

Phase 2C: Validate Mode

Read all string table files in assets/data/strings/. For each locale, check:

• Completeness — key exists in source (en) but no translation for this locale
• Placeholder mismatches — source has {name} but translation omits it or adds extras
• String length violations — translation exceeds the character limit recorded in the source context field
• Plural form count — locale requires N plural forms; translation provides fewer
• Orphaned keys — translation exists but nothing in the code root references the key
• Stale translations — source string changed after translation was written (flag for re-translation)
• Encoding — non-ASCII characters present and font atlas supports them (flag if uncertain)

Report validation results grouped by locale and severity. This mode is read-only — no files are written.

Phase 2D: Status Mode

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

## Localization Status
Generated: [Date]
String freeze: [Active / Not yet called / Lifted]

This mode is read-only — no files are written.

Phase 2E: Brief Mode

Generate a translator context briefing document. This document is sent to the external translation team or localisation vendor alongside the string table export.

Read:

• design/gdd/ — extract game genre, tone, setting, character names
• assets/data/strings/strings-en.json — the source string table
• Any existing lore or narrative documents in design/narrative/

Generate production/localization/translator-brief-[locale]-[date].md:

Ask: "May I write this translator brief to production/localization/translator-brief-[locale]-[date].md?"

Phase 2F: Cultural Review Mode

Spawn localization-lead via Agent. Ask them to audit the following for cultural sensitivity across the target locales (read from assets/data/strings/ and assets/):

Content Areas to Review

Symbols and gestures

• Thumbs up, OK hand, peace sign — meanings vary by region
• Religious or spiritual symbols in art, UI, or audio
• National flags, map representations, disputed territories

Colours

• White (mourning in some Asian cultures), green (political associations in some regions), red (luck vs danger)
• Alert/warning colours that conflict with cultural associations

Numbers

• 4 (death in Japanese/Chinese), 13, 666 — flag use in UI (room numbers, item counts, prices)

Humour and idioms

• Idioms that translate as offensive in other locales
• Toilet/bodily humour that is inappropriate in some markets (notably Japan, Germany, Middle East)
• Dark humour around topics that are culturally sensitive in specific regions

Violence and content ratings

• Content that would require ratings changes in DE (Germany), AU (Australia), CN (China), or AE (UAE)
• Blood colour, gore level, drug references — flag all for region-specific asset variants if needed

Names and representations

• Character names that are offensive, profane, or carry negative meaning in target locales
• Stereotyped representation of nationalities, religions, or ethnic groups

Present findings as a table:

BLOCKING = must fix before shipping that locale. ADVISORY = recommend change. NOTE = informational only.

Ask: "May I write this cultural review report to production/localization/cultural-review-[date].md?"

Phase 2G: VO Pipeline Mode

Manage the voice-over localization process. Determine the sub-task from the argument:

• vo-pipeline scan — identify all dialogue lines that require VO recording
• vo-pipeline script — generate recording scripts with director notes
• vo-pipeline validate — check that all recorded VO files are present and correctly named
• vo-pipeline integrate — verify VO files are correctly referenced in code/assets

VO Pipeline: Scan

Read assets/data/strings/ and design/narrative/. Identify:

• All dialogue lines (keys matching dialogue.*) with source text
• Lines already recorded (audio file exists in assets/audio/vo/)
• Lines not yet recorded

Output a recording manifest:

VO Pipeline: Script

Generate a recording script document for each character, grouped by scene. Include:

• Character name and brief personality note
• Full dialogue line with pronunciation guide for unusual proper nouns
• Emotion/direction note for each line ([Warm, welcoming], [Annoyed, clipped])
• Any lines that are responses in a conversation (provide context: "Player just said X")

Ask: "May I write the VO recording scripts to production/localization/vo-scripts-[locale]-[date].md?"

VO Pipeline: Validate

Glob assets/audio/vo/[locale]/ for all .wav/.ogg files. Cross-reference against the VO manifest. Report:

• Missing files (line in script, no audio file)
• Extra files (audio file exists, no matching string key)
• Naming convention violations

VO Pipeline: Integrate

Grep the code root for VO audio references. Verify each referenced path exists in assets/audio/vo/[locale]/. Report broken references.

Phase 2H: RTL Check Mode

Right-to-left languages (Arabic, Hebrew, Persian, Urdu) require layout mirroring beyond just translating text. This mode validates the implementation.

Determine the engine: read engine.name from project.yaml; if that key is absent or empty (including when project.yaml has no engine: block), fall back to .claude/docs/technical-preferences.md. Then check:

Layout mirroring

• Is RTL layout enabled in the engine? (Godot: Control.layout_direction, Unity: RTL Support package, Unreal: text direction flags)
• Are all UI containers set to auto-mirror, or are positions hardcoded?
• Do progress bars, health bars, and directional indicators mirror correctly?

Text rendering

• Are fonts loaded that support Arabic/Hebrew character sets?
• Is Arabic text rendered with correct ligatures (connected script)?
• Are numbers displayed as Eastern Arabic numerals where required?

String assembly

• Are there any string concatenations that assume left-to-right reading order?
• Do {placeholder} positions in sentences work correctly when sentence structure is reversed?

Asset review

• Are there UI icons with directional arrows or asymmetric designs that need mirrored variants?
• Do any text-in-image assets exist that require RTL versions?

Grep patterns to check:

• Engine-specific RTL flags in scene/prefab files
• Any HBoxContainer, LinearLayout, HorizontalBox nodes — verify layout_direction settings
• String concatenation with + near dialogue or UI code

Report findings. Flag BLOCKING issues (content unreadable without fix) vs ADVISORY (cosmetic improvements).

Ask: "May I write this RTL check report to production/localization/rtl-check-[date].md?"

Phase 2I: Freeze Mode

String freeze locks the source (English) string table so that translations can proceed without the source changing under the translators.

freeze call

Check current freeze status in production/localization/freeze-status.md (if it exists).

If already frozen:

"String freeze is currently ACTIVE (called [date]). [N] strings have been added or modified since freeze. These are freeze violations — they require re-translation or an approved freeze lift."

If not frozen, present the pre-freeze checklist:

Use AskUserQuestion:

• Prompt: "Call string freeze now? This writes production/localization/freeze-status.md (Status: ACTIVE) and locks the source table."
• Options: [A] Yes — call string freeze now / [B] No — I still have strings to add

If [A]: Write production/localization/freeze-status.md:

freeze lift

If argument includes lift: ask "May I update freeze-status.md to LIFTED?", then set its Status to LIFTED and record the reason and date. Warn: "Lifting the freeze requires re-translation of all modified strings. Notify the translation team."

freeze check (auto-integrated into extract)

When extract mode finds new or modified strings and freeze-status.md shows Status: ACTIVE — name freeze-status.md in extract's own "May I write" question, append the new keys to its ## Post-Freeze Changes on approval, and warn:

"⚠️ String freeze is active. [N] new/modified strings have been added. These are freeze violations. Notify your localization vendor before proceeding."

Phase 2J: QA Mode

Localization QA is a dedicated pass that runs after translations are delivered but before any locale ships. This is not the same as /localize validate (which checks completeness) — this is a structured playthrough-based quality check.

Spawn localization-lead via Agent with:

• The target locale(s) to QA
• The list of all screens/flows in the game (from design/gdd/ or /content-audit output)
• The current /localize validate report
• The cultural review report (if it exists)

Ask the localization-lead to produce a QA plan covering:

1. Functional string check — every string displays in-game without truncation, placeholder errors, or encoding corruption
2. UI overflow check — translated strings that exceed UI bounds (even if within character limits, some languages expand)
3. Contextual accuracy — a sample of 10% of strings reviewed in-game for translation accuracy and natural phrasing
4. Cultural review items — verify all BLOCKING items from the cultural review are resolved
5. VO sync check — if VO exists, verify lip sync or subtitle timing is acceptable after translation
6. Platform cert requirements — check platform-specific localization requirements (age ratings text, legal notices, ESRB/PEGI/CERO text)

Output a QA verdict per locale:

First match wins: FAIL if any BLOCKING finding is open; else NOT ASSESSED if a check could not run — the checks are playthrough-based, so a locale nobody has played in-game (or whose translations were not delivered) cannot pass on the string tables alone; name each check that did not run; else PASS WITH CONDITIONS if conditions remain; else PASS. NOT ASSESSED outranks both pass values — an unplayed locale has not passed — and ranks below FAIL, so an open BLOCKING finding is never buried behind it.

Ask: "May I write this localization QA report to production/localization/loc-qa-[locale]-[date].md?"

Gate integration: At workflow: full, the Polish → Release gate requires a PASS or PASS WITH CONDITIONS verdict for every translated locale being shipped (recommended at standard; dropped at minimal). A FAIL blocks release for that locale only — other locales may still proceed if their QA passes. A NOT ASSESSED locale has not passed: its QA did not run.

Phase 3: Rules and Next Steps

Rules

• English (en) is always the source locale
• Every string table entry must include a context field with translator notes, character limits, and placeholder meaning
• Never modify translation files directly — generate diffs for review
• Character limits must be defined per-UI-element and enforced in validate mode
• String freeze must be called before sending strings to translators — never translate a moving target
• RTL support must be designed in from the start — retrofitting RTL layout is expensive
• Cultural review is required for any locale where the game will be sold commercially
• VO scripts must include director notes — raw dialogue lines produce flat recordings

Recommended Workflow

After qa returns PASS or PASS WITH CONDITIONS for every translated locale you ship, include the QA report paths when running /gate-check release.