# Game RPG Localization Runtime Guide

This guide covers the `LocalizationSubsystem` runtime surface for shipping text
and voice in multiple locales.

## String And Vendor Workflow

Author source strings with hierarchical IDs such as `quest.main_01.title` and
`ui.menu.options`. Use the extraction helpers to scan code and game data, build
JSON/XLIFF translation files, push source strings to the configured translation
management adapter, then pull completed locale files back into the asset build.

Each translation unit carries source text, target text, context, character
limits, variables, review status, and screenshot references. QA should run on
every pulled file before localized assets are shipped.

## Text Runtime

Use CJK coverage validation with the font coverage data exported by the engine
or build pipeline. The validator checks every translated character against the
font coverage source and reports the string IDs where missing glyphs appear.

For CJK layout, run line breaking before text measurement so Japanese, Chinese,
and Korean punctuation is kept with the preceding line. Use the density planner
to decide whether a label or text area needs more width, more lines, or a
readable font-size adjustment.

For RTL locales, prepare text through the RTL render plan. Engines with shaping
support should provide a shaping adapter; the plan still adds direction,
punctuation mirroring, and Unicode isolation metadata for mixed LTR/RTL text.
Use the UI mirroring helper to flip HUD, menu, and navigation anchors across the
viewport.

## Voice-Over Runtime

Voice-over assets live under a per-locale root:

```text
vo/{locale}/{string-id-segments}.{format}
```

For example:

```text
vo/ja-JP/dialogue/blacksmith/greeting.wav
```

The asset validator checks path layout, audio format, sample rate, channel
count, and clip duration. The matching pipeline compares localized dialogue
lines with available assets and returns coverage, missing line IDs, and invalid
asset issues.

Recording script export produces a readable actor script and CSV with line ID,
locale, character, context, direction, and localized text. Lip-sync generation
accepts an audio-analysis adapter when the engine provides one and otherwise
builds deterministic transcript-aligned phoneme marks. Subtitle timing uses the
VO clip duration when present and falls back to localized reading duration.

## Locale Selection

The runtime exposes a locale-selection model rather than a rendered options
screen. Game clients can bind the model to their UI controls:

- text language options
- voice language options
- subtitle language options
- OS locale auto-detection
- separate text and VO overrides
- RTL direction metadata per option

If a recorded VO asset is missing and accessibility fallback is enabled, the
text-to-speech resolver can call the platform provider and return the generated
asset.

## QA And Release Gates

Run the package checks before a localization release:

```bash
pnpm --dir libs/aphrodite/game-rpg exec tsc -p tsconfig.spec.json --noEmit
pnpm --dir libs/aphrodite/game-rpg lint
pnpm --dir libs/aphrodite/game-rpg build
pnpm --dir libs/aphrodite/game-rpg test
```

Localization CI should also run:

- string extraction and TMS sync
- translation QA for missing text, copied source text, invalid variables,
  encoding issues, and length budgets
- CJK font coverage validation
- RTL render-plan checks for Arabic/Hebrew locales
- VO asset coverage and audio contract validation
- pseudo-localization builds
- localization testing mode to capture every configured screen for every locale
