Eve library

Game RPG Localization Runtime Guide

Guide

Revision 1

On this page

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