@zigrivers/scaffold 3.4.1 → 3.5.0

package/content/knowledge/game/game-liveops-analytics.md

@@ -0,0 +1,280 @@
+---
+name: game-liveops-analytics
+description: Data taxonomy, telemetry pipelines, A/B testing, content cadence, seasonal events, post-launch support, and KPI-driven decision making
+topics: [game-dev, analytics, liveops, telemetry, kpi, ab-testing]
+---
+
+Live operations (LiveOps) and analytics transform a game from a one-time product into a continuously evolving service. The core discipline is building feedback loops: instrument player behavior, analyze the data, form hypotheses, ship changes, measure results. Without robust telemetry and a clear KPI hierarchy, LiveOps teams operate blind — making content decisions based on gut feel, missing retention cliffs, and shipping events that move no needle. Games that invest in data infrastructure from early production gain a compounding advantage: every content update is informed by the last, every A/B test sharpens understanding of the player base, and every seasonal event builds on measured engagement patterns.
+
+## Summary
+
+### Data Taxonomy and KPI Hierarchy
+
+Game analytics requires a structured taxonomy that separates vanity metrics from actionable KPIs. The hierarchy flows from business health (revenue, growth) down to behavioral signals (progression, session patterns).
+
+**Top-Level Health Metrics:**
+- **DAU / MAU** — Daily and Monthly Active Users; the MAU/DAU ratio (stickiness) reveals whether players return habitually or sporadically
+- **D1 / D7 / D30 Retention** — Percentage of new users returning after 1, 7, and 30 days; the single most important metric for predicting long-term viability
+- **ARPDAU** — Average Revenue Per Daily Active User; revenue efficiency independent of install volume
+- **LTV** — Lifetime Value; total revenue a player generates before churning; must exceed Customer Acquisition Cost (CAC) by 3x+ for sustainable growth
+- **Conversion Rate** — Percentage of free players who make any purchase; typical F2P range is 2-5%
+
+**Mid-Level Engagement Metrics:**
+- **Session Length** — Average time per play session; declining session length is an early churn signal
+- **Sessions Per Day** — Frequency of return within a single day; driven by energy systems, daily rewards, social obligations
+- **Progression Velocity** — How fast players advance through content; too fast causes content drought, too slow causes frustration drop-off
+- **Feature Adoption Rate** — Percentage of eligible players who engage with a new feature within 7 days of exposure
+
+**Behavioral Signals:**
+- **Funnel Drop-Off** — Where players abandon a sequence (tutorial, purchase flow, onboarding); each step should retain 85%+ of the previous step
+- **Content Completion Rate** — Percentage of players who finish a level, quest, or event; signals difficulty calibration
+- **Social Actions** — Friend adds, guild joins, co-op sessions; social bonds are the strongest retention predictor
+- **Error / Crash Rate** — Technical failures per session; crashes in the first 5 minutes destroy D1 retention
+
+### Content Cadence and Seasonal Events
+
+LiveOps calendars follow predictable rhythms that align with player expectations and real-world events:
+
+- **Weekly**: Rotating challenges, leaderboard resets, limited-time modes
+- **Bi-weekly**: New content drops (characters, maps, items) to sustain engagement between major updates
+- **Monthly**: Season passes or battle passes with a progression track; ~28-day duration with 2-3 day overlap for late completionists
+- **Quarterly**: Major content updates (new regions, story chapters, mechanical expansions)
+- **Seasonal**: Holiday events (Halloween, Lunar New Year, summer) with themed cosmetics and limited-time mechanics
+
+Each content beat should have a clear engagement target and revenue hypothesis before development begins.
+
+### A/B Testing Pipeline
+
+A/B testing in games requires careful population segmentation to avoid contaminating the experience of players who interact with each other (e.g., different prices in a shared economy).
+
+## Deep Guidance
+
+### Telemetry Architecture
+
+A production telemetry pipeline has four layers: instrumentation, ingestion, processing, and visualization. Each layer must handle the scale of a live game — millions of events per minute at peak.
+
+**Instrumentation Layer:**
+
+Every telemetry event should follow a consistent schema. Define a base event envelope that every event extends:
+
+```json
+{
+  "event_id": "uuid-v4",
+  "event_name": "level_complete",
+  "timestamp": "2026-01-15T14:32:01.442Z",
+  "client_version": "2.4.1",
+  "platform": "ios",
+  "device_model": "iPhone15,2",
+  "user_id": "player_abc123",
+  "session_id": "sess_def456",
+  "properties": {
+    "level_id": "world3_stage7",
+    "duration_seconds": 142,
+    "deaths": 3,
+    "score": 28400,
+    "items_used": ["health_potion", "speed_boost"],
+    "difficulty": "normal"
+  }
+}
+```
+
+Instrumentation rules:
+- Every event gets a UUID, ISO-8601 timestamp, client version, platform, and session ID — no exceptions
+- Property names use snake_case; values use consistent types (never mix string "3" with integer 3)
+- Batch events client-side and flush every 30 seconds or when the batch reaches 50 events, whichever comes first
+- Buffer events to local storage during offline play; flush when connectivity returns
+- Never log personally identifiable information (PII) in telemetry — hash or anonymize user identifiers
+- Tag events with the current A/B test assignments so every analysis can be segmented by experiment
+
+**Ingestion Layer:**
+
+Use a message queue (Kafka, AWS Kinesis, Google Pub/Sub) to decouple event producers from consumers. This absorbs traffic spikes during peak hours and event launches without dropping data.
+
+Design for at-least-once delivery. Events may arrive duplicated; deduplication happens in the processing layer using event_id. Design ingestion endpoints to accept gzip-compressed payloads — mobile clients on cellular networks send 60-80% less data when compressed.
+
+**Processing Layer:**
+
+Raw events flow into a data lake (S3, GCS) partitioned by date and event name. A streaming processor (Apache Flink, Spark Streaming, or a simpler Lambda/Cloud Function pipeline) handles:
+
+1. **Deduplication** — Remove events with duplicate event_id values
+2. **Enrichment** — Join with user profile data (install date, country, cohort, spending tier)
+3. **Aggregation** — Compute real-time metrics (concurrent users, revenue per minute, error rates)
+4. **Alerting** — Trigger alerts when metrics breach thresholds (crash rate > 2%, revenue drops > 20% hour-over-hour)
+
+**Visualization Layer:**
+
+Dashboards should be organized by audience:
+- **Executive dashboard**: DAU, revenue, D1/D7/D30 retention, top-line conversion — updated daily
+- **LiveOps dashboard**: Event participation, content completion, store performance — updated hourly
+- **Engineering dashboard**: Crash rates, API latency, matchmaking queue times, server load — real-time
+- **Game design dashboard**: Progression funnels, difficulty curves, economy flow rates — updated daily
+
+### Progression Funnel Analysis
+
+The most actionable analysis in game analytics is funnel tracking through key progression milestones. Every game has a "critical path" — the sequence of actions a player must complete to reach the core loop.
+
+Example funnel for a mobile RPG:
+
+```
+Stage                    | % of Installs | Drop-off
+─────────────────────────┼───────────────┼─────────
+App opened               | 100%          | —
+Tutorial started         | 95%           | 5%
+Tutorial completed       | 72%           | 23%  ← RED FLAG
+First battle won         | 68%           | 4%
+Reached town hub         | 61%           | 7%
+Equipped first item      | 54%           | 7%
+Completed Chapter 1      | 41%           | 13%
+First IAP prompt seen    | 38%           | 3%
+First IAP purchased      | 4.2%          | 33.8%
+Reached Chapter 3        | 22%           | 16%
+Joined a guild           | 12%           | 10%
+```
+
+Red flag analysis: A 23% drop-off during tutorial is critical. Investigate by segmenting:
+- By platform (iOS vs Android) — Android devices have wider performance variance; tutorial may stutter on low-end hardware
+- By acquisition source — Players from rewarded ads have lower intent than organic installs
+- By tutorial step — Identify the exact screen or interaction where players quit
+- By session duration — Did they play for 10 seconds (never engaged) or 3 minutes (confused)?
+
+Target benchmarks: Tutorial completion should be 80%+. If below 70%, the tutorial is broken, not the players.
+
+### A/B Testing Methodology
+
+A/B testing in games differs from web A/B testing in three critical ways:
+
+1. **Social contamination** — Players talk. If Group A gets better rewards than Group B, players will notice and complain on forums. Segment tests to avoid visible inequality.
+2. **Long feedback loops** — A web test shows results in hours. Game economy tests need 14-30 days to show downstream effects on retention and spending.
+3. **State persistence** — You cannot easily "undo" a game economy change. If Group A received double gold for a week, reverting creates a perceived loss.
+
+**Test design framework:**
+
+```python
+# A/B Test Configuration Schema
+class ABTest:
+    test_id: str              # "spring_2026_pricing_v2"
+    hypothesis: str           # "Lowering starter pack price from $4.99 to $2.99
+                              #  will increase conversion by >30% without
+                              #  reducing D30 ARPDAU"
+    primary_metric: str       # "conversion_rate_d7"
+    secondary_metrics: list   # ["arpdau_d30", "d7_retention", "iap_count_d30"]
+    guardrail_metrics: list   # ["crash_rate", "session_length", "d1_retention"]
+    population: str           # "new_users_after_2026-03-01"
+    allocation: dict          # {"control": 50, "variant_a": 50}
+    min_sample_size: int      # 10000 per arm (calculated for 80% power, 5% significance)
+    duration_days: int        # 14
+    segment_exclusions: list  # ["whales_ltv_over_500", "employees"]
+```
+
+**Sample size calculation**: For a 5% baseline conversion rate and a minimum detectable effect of 20% relative (i.e., detecting a move from 5.0% to 6.0%), you need approximately 25,000 users per arm at 80% power and 95% confidence. Under-powered tests waste time — they run for weeks and produce inconclusive results.
+
+**Guardrail metrics**: Every test must define guardrail metrics that auto-halt the test if breached. If a pricing test increases conversion but crashes D1 retention by 5%, the test should stop immediately regardless of the primary metric.
+
+### Seasonal Event Design
+
+Successful seasonal events follow a predictable structure:
+
+**Pre-event (7-14 days before):**
+- Tease event through in-game mail, loading screens, social media
+- Update app store screenshots and feature graphics
+- Pre-load event assets in a background download to avoid day-one download friction
+- Verify server capacity for expected traffic spike (typically 1.5-3x normal DAU)
+
+**Event runtime (7-28 days):**
+- Clear event UI that shows progress, time remaining, and reward tiers
+- Multiple engagement tracks: casual track (play normally, earn event currency), hardcore track (special challenges for exclusive rewards)
+- Pacing curve: easy early milestones to hook participation, escalating effort toward the end
+- Mid-event content drop (new challenges, bonus multiplier) to re-engage players who stalled
+- Daily login bonus specific to the event to maintain return frequency
+
+**Post-event (3-7 days after):**
+- Grace period for players to spend remaining event currency
+- Event recap (your stats, leaderboard rank, rewards earned)
+- Remove event UI but keep earned items/cosmetics permanently
+- Publish event retrospective internally: participation rate, revenue lift, retention impact, what worked, what didn't
+
+**Revenue integration**: Seasonal events are the highest-revenue windows. Offer event-exclusive bundles, a paid event pass (premium track), and limited-time cosmetics. Price anchoring: show a "full value" price crossed out next to the bundle price. Time pressure ("3 days remaining") drives conversion.
+
+### Server Maintenance Communication
+
+Planned maintenance communication follows a strict timeline:
+
+```
+T-72h  — First announcement: in-game banner, website, social media, Discord
+T-24h  — Reminder with exact time, expected duration, and timezone conversions
+T-4h   — Final reminder; disable new matchmaking / long-duration activities
+T-1h   — Persistent in-game popup: "Maintenance in 60 minutes. Save your progress."
+T-15m  — Force-save all player state; prevent new session starts
+T-0    — Servers go down; redirect all clients to maintenance screen with ETA
+T+done — Servers up; push notification: "We're back! Log in for compensation reward"
+```
+
+Always over-estimate downtime publicly. If maintenance takes 2 hours, announce 4 hours. Finishing early feels like a gift; running late feels like incompetence.
+
+**Compensation formula**: For every hour of unplanned downtime, grant premium currency equal to 1 hour of median free-player earning rate. For planned maintenance during announced windows, compensation is optional but goodwill-positive — a small gift (stamina refill, daily reward chest) keeps sentiment positive.
+
+### Post-Launch Support Workflow
+
+Post-launch LiveOps follows a weekly cadence:
+
+**Monday**: Review weekend metrics (weekends are peak). Identify anomalies. Prioritize issues.
+
+**Tuesday-Wednesday**: Ship hotfixes for critical bugs. Deploy content updates. Activate weekly events.
+
+**Thursday**: A/B test analysis meeting. Review running tests, check for significance, decide on early stops.
+
+**Friday**: Plan next week's content. Approve store rotations. Draft social media calendar.
+
+**Continuous**: Monitor real-time dashboards for crash spikes, revenue anomalies, and exploit reports. On-call rotation covers evenings and weekends.
+
+### Economy Health Monitoring
+
+A game economy requires continuous monitoring to detect inflation, deflation, and exploit-driven imbalances:
+
+```yaml
+# Economy Health Dashboard Alerts
+alerts:
+  - name: currency_inflation
+    metric: avg_soft_currency_balance
+    condition: "> 2x baseline_30d_average"
+    severity: P1
+    action: "Investigate new currency sources; check for duplication exploits"
+
+  - name: sink_failure
+    metric: daily_currency_sink_rate
+    condition: "< 60% of daily_currency_source_rate"
+    severity: P2
+    action: "Economy is inflating; add or strengthen sinks"
+
+  - name: conversion_collapse
+    metric: iap_conversion_rate_d7
+    condition: "< 50% of trailing_30d_average"
+    severity: P0
+    action: "Immediate investigation; check store, pricing, paywall"
+
+  - name: whale_concentration
+    metric: top_1pct_revenue_share
+    condition: "> 70%"
+    severity: P2
+    action: "Revenue overly dependent on whales; diversify monetization"
+
+  - name: new_user_economy
+    metric: d3_soft_currency_median
+    condition: "< tutorial_cost * 0.5"
+    severity: P1
+    action: "New players cannot afford basic upgrades; increase early grants"
+```
+
+**Sink-source balance**: Track every currency source (quest rewards, daily login, event prizes, IAP) and every currency sink (upgrades, gacha pulls, cosmetics, energy refills). Plot the net flow daily. A healthy economy has sinks consuming 70-90% of generated currency, with the remaining 10-30% accumulating as player savings that create investment and loss aversion.
+
+### Cohort Analysis
+
+Never look at aggregate metrics alone. Always segment by cohort:
+
+- **Install date cohort** — D30 retention for January installs vs February installs reveals whether game changes helped or hurt
+- **Spending tier cohort** — Free, minnow ($1-$10 LTV), dolphin ($10-$100 LTV), whale ($100+ LTV) behave completely differently
+- **Acquisition source cohort** — Organic installs have 2-3x better retention than paid installs from rewarded ad networks
+- **Platform cohort** — iOS players typically have 1.5-2x higher ARPDAU than Android players
+- **Geography cohort** — Tier-1 markets (US, UK, Japan, Korea) have radically different spending patterns than Tier-3 markets
+
+A metric moving in aggregate can mask opposite movements in sub-populations. DAU can be flat while D1 retention drops 10% — because a marketing campaign is backfilling with low-quality installs at the same rate as churn.

package/content/knowledge/game/game-localization.md

@@ -0,0 +1,323 @@
+---
+name: game-localization
+description: String management, font atlas pipeline, text expansion, subtitle standards, VO localization, culturalization, and LQA methodology
+topics: [game-dev, localization, l10n, lqa, fonts, rtl]
+---
+
+Game localization is not translation — it is the engineering and cultural adaptation required to make a game feel native in every target market. A translated string that does not fit the UI, a font that cannot render Chinese characters, a gesture that is offensive in Brazil, or a subtitle that flashes too fast for reading speed norms — each of these failures breaks immersion and signals to the player that they are an afterthought. Localization touches every layer of the stack: string management, rendering, audio, UI layout, cultural review, and QA. The cost of retrofitting localization into a game that was not designed for it is 3-5x higher than building it in from the start.
+
+## Summary
+
+### String Management Systems
+
+All player-facing text must be externalized into string tables, never hardcoded. The string management pipeline has three components: authoring (developers write string IDs), translation (translators produce localized variants), and integration (the game loads the correct variant at runtime).
+
+**String ID conventions:**
+- Use hierarchical, descriptive IDs: `ui.main_menu.play_button`, `dialogue.npc_blacksmith.greeting_01`
+- Never use the English text as the key — English text changes during development, breaking all translations
+- Prefix system strings vs content strings: `sys.error.connection_lost` vs `content.quest.dragon_slayer.desc`
+- Include context hints in comments: `/* Button label, max 12 chars */` helps translators make appropriate choices
+
+**Text expansion rules by language:**
+- English (source) → German: +30% average, up to +50% for short strings
+- English → Finnish: +30-40%
+- English → French: +15-20%
+- English → Spanish: +15-25%
+- English → Japanese: -10-30% (fewer characters but may need more vertical space)
+- English → Chinese (Simplified): -30-50% in character count but wider individual glyphs
+- English → Korean: -10-20% character count
+- English → Arabic/Hebrew (RTL): Similar length but requires full layout mirroring
+
+UI must accommodate the worst-case expansion. A button designed to fit "Play" (4 chars) must also fit "Spielen" (7 chars, German) without truncation or overflow.
+
+### Font Atlas and Rendering
+
+Latin-alphabet games can use a single font atlas with 200-300 glyphs. CJK (Chinese, Japanese, Korean) localization requires thousands of glyphs, fundamentally changing the font rendering strategy.
+
+**CJK considerations:**
+- Japanese requires ~2,200 Joyo kanji + hiragana + katakana (~3,000 glyphs minimum)
+- Chinese Simplified requires ~6,500 common characters (GB2312 set) for full coverage
+- Korean Hangul has 11,172 possible syllable blocks; pre-composed sets of ~2,500 cover 99% of text
+- Static font atlases at this scale consume 16-64 MB of texture memory
+- Dynamic font rendering (runtime rasterization with caching) is preferred for CJK — render glyphs on demand and cache to atlas
+
+**RTL (Right-to-Left) languages:**
+- Arabic and Hebrew text flows right-to-left, but numbers and Latin text embedded within flow left-to-right (bidirectional text)
+- UI layouts must mirror: scrollbars move to the left, progress bars fill right-to-left, navigation reverses
+- Arabic requires contextual shaping — each letter has up to 4 forms depending on position (initial, medial, final, isolated)
+- Arabic text cannot simply be reversed string — a shaping engine (HarfBuzz, ICU) must process it
+
+### Subtitle and Caption Standards
+
+Subtitle presentation has measurable impact on comprehension and player experience. Industry standards from film and broadcast apply, with game-specific additions.
+
+## Deep Guidance
+
+### String Extraction and Translation Pipeline
+
+The localization pipeline begins with string extraction and ends with integrated, tested builds in every supported language.
+
+**Step 1: String extraction**
+
+All strings live in a structured format that supports translator context:
+
+```json
+{
+  "strings": [
+    {
+      "id": "ui.hud.health_label",
+      "source": "Health",
+      "context": "HUD label next to health bar. Max 10 characters.",
+      "max_length": 10,
+      "tags": ["ui", "hud"],
+      "screenshot": "assets/loc_screenshots/hud_health.png"
+    },
+    {
+      "id": "ui.shop.buy_button",
+      "source": "Buy Now",
+      "context": "Purchase button in item shop. Should convey urgency.",
+      "max_length": 15,
+      "tags": ["ui", "shop", "monetization"],
+      "screenshot": "assets/loc_screenshots/shop_buy.png"
+    },
+    {
+      "id": "dialogue.guard.warning_01",
+      "source": "Halt! No one passes without the captain's seal.",
+      "context": "Spoken by gate guard NPC. Stern, military tone.",
+      "max_length": null,
+      "tags": ["dialogue", "npc"],
+      "voice_acted": true,
+      "character": "Guard Captain Aldric"
+    }
+  ]
+}
+```
+
+**Step 2: Translation Management System (TMS)**
+
+Use a TMS (Crowdin, Lokalise, Phrase, memoQ) rather than spreadsheets. TMS platforms provide:
+- Translation memory (TM) — previously translated strings are suggested automatically, ensuring consistency and reducing cost
+- Glossary enforcement — key terms (character names, game mechanics, UI labels) are locked to approved translations
+- In-context editing — translators see the string alongside a screenshot of where it appears in-game
+- Pseudo-localization — generates fake translations that simulate text expansion and character coverage for testing before real translations arrive
+- Branch-aware workflows — translations track the development branch, merge with code, and flag conflicts
+
+**Step 3: Integration and build**
+
+```bash
+#!/usr/bin/env bash
+# loc-build.sh — Pull translations and build localized assets
+set -euo pipefail
+
+TMS_PROJECT_ID="${TMS_PROJECT_ID:?Set TMS_PROJECT_ID}"
+SUPPORTED_LANGS=("en" "de" "fr" "es" "ja" "ko" "zh-Hans" "zh-Hant" "ar" "pt-BR" "ru")
+
+echo "=== Pulling translations from TMS ==="
+for lang in "${SUPPORTED_LANGS[@]}"; do
+  echo "  Pulling ${lang}..."
+  tms-cli pull --project "$TMS_PROJECT_ID" \
+    --language "$lang" \
+    --output "assets/localization/${lang}.json" \
+    --format structured-json
+done
+
+echo "=== Validating translations ==="
+for lang in "${SUPPORTED_LANGS[@]}"; do
+  echo "  Validating ${lang}..."
+  # Check for missing translations
+  loc-validator check-completeness \
+    --source "assets/localization/en.json" \
+    --target "assets/localization/${lang}.json" \
+    --fail-on-missing
+
+  # Check max_length constraints
+  loc-validator check-length \
+    --target "assets/localization/${lang}.json" \
+    --fail-on-overflow
+
+  # Check for placeholder consistency ({name}, {count}, etc.)
+  loc-validator check-placeholders \
+    --source "assets/localization/en.json" \
+    --target "assets/localization/${lang}.json"
+done
+
+echo "=== Building font atlases ==="
+for lang in "${SUPPORTED_LANGS[@]}"; do
+  font-builder build \
+    --language "$lang" \
+    --strings "assets/localization/${lang}.json" \
+    --output "assets/fonts/${lang}_atlas.png" \
+    --sdf-mode
+done
+
+echo "=== Localization build complete ==="
+```
+
+### Font Rendering Pipeline
+
+For CJK languages, static pre-baked font atlases are impractical. The standard approach is a dynamic Signed Distance Field (SDF) font renderer:
+
+1. **Pre-seed the atlas** — At load time, rasterize the 500 most common characters for the target language into an SDF texture atlas
+2. **Runtime rasterization** — When the text renderer encounters a glyph not in the atlas, rasterize it from the TrueType/OpenType font file, generate the SDF, and pack it into the atlas
+3. **Atlas management** — Use a shelf-packing algorithm. When the atlas fills (typically 2048x2048 or 4096x4096), evict least-recently-used glyphs
+4. **Fallback fonts** — If the primary font lacks a glyph (e.g., a Latin font missing CJK characters), fall back to Noto Sans CJK or a platform system font
+
+SDF fonts scale cleanly at any size without regeneration, support outlines and drop shadows in the shader, and consume less memory than bitmap fonts at equivalent quality.
+
+**Memory budgets for font atlases:**
+- Latin-only game: 1-2 MB (one 1024x1024 RGBA atlas)
+- CJK support: 8-16 MB (one 4096x4096 atlas with dynamic packing)
+- Full global language support including Arabic shaping: 16-32 MB
+
+### RTL Implementation Guide
+
+Right-to-left support requires changes at three levels: text rendering, UI layout, and content design.
+
+**Text rendering:**
+- Integrate a Unicode bidirectional algorithm (UAX #9) implementation — ICU or FriBidi
+- The algorithm determines the correct visual order for mixed-direction text (Arabic words interspersed with English brand names and numbers)
+- Arabic contextual shaping: use HarfBuzz or platform-native text shaping. Each Arabic letter changes form based on its neighbors. Simple string reversal produces garbage.
+- Diacritical marks (tashkeel) in Arabic must be positioned correctly above/below base characters
+
+**UI layout mirroring:**
+- Horizontal layouts reverse: left-aligned text becomes right-aligned, left-margin becomes right-margin
+- Navigation flows reverse: "next" arrows point left, "back" arrows point right
+- Progress bars and sliders fill from right to left
+- Scrollbars move to the left side
+- Icons that convey direction (arrows, pointing hands) must be mirrored; icons that do not convey direction (a clock, a star) must NOT be mirrored
+- Implement a layout direction flag (`isRTL`) that UI containers check when positioning children
+
+**Exceptions to mirroring:**
+- Phone number fields stay LTR (numbers are universal)
+- Timestamps remain in local convention
+- Media playback controls (play, fast-forward) are not mirrored — these are universal symbols
+- Latin text within an RTL context keeps its LTR direction (handled by the bidi algorithm)
+
+### Subtitle and Caption Standards
+
+Subtitle presentation follows established readability guidelines:
+
+**Timing:**
+- Minimum display time: 1.5 seconds (even for very short text)
+- Maximum display time: 7 seconds per subtitle block
+- Reading speed: 15-20 characters per second for adults; 12-15 for children's games
+- Gap between consecutive subtitles: minimum 0.25 seconds (allows the eye to register a change)
+
+**Formatting:**
+- Maximum 2 lines per subtitle block
+- Maximum 42 characters per line (including spaces)
+- Use sentence case, not ALL CAPS (all caps reduces readability by 10-15%)
+- Speaker identification for off-screen characters: brackets or colored text
+- Italics for off-screen dialogue, narration, or internal monologue
+- Sound effect descriptions in square brackets for accessibility: `[explosion]`, `[footsteps approaching]`
+
+**Positioning:**
+- Default position: bottom-center of screen, above any HUD elements
+- When a HUD element overlaps, subtitles shift upward dynamically
+- For VR: subtitles are world-locked (not head-locked) at 2-3 meters from the player, slightly below eye level
+- Speaker-specific positioning: in multiplayer or scenes with multiple speakers, position subtitles near the speaker
+
+### Voice-Over Localization
+
+VO localization is the most expensive and complex localization task. Two strategies exist:
+
+**Full dubbing:**
+- Record all dialogue in every target language
+- Requires casting voice actors for each language — matching tone, age, and personality of the original performance
+- Lip-sync must be re-targeted (a major animation cost) or the game uses faceless/masked characters to avoid the issue
+- Cost: $0.30-$0.80 per word per language for professional studio recording
+- Timeline: 4-8 weeks per language after scripts are locked
+- Best for story-driven games (RPGs, adventure games) where VO is central to the experience
+
+**Subtitles only (original VO):**
+- Keep the original language VO; translate text only
+- Dramatically cheaper and faster
+- Players hear the original performance, which is often preferred for stylized games (anime-style, distinct cultural settings)
+- Adequate for most indie and AA games, and for languages with smaller markets
+
+**Hybrid approach:**
+- Dub into the 3-5 largest markets (English, Japanese, French, German, Spanish) and subtitle the rest
+- This is the AAA standard for cost-effective global reach
+
+**VO production workflow:**
+1. Lock dialogue scripts (no changes after this point without re-recording)
+2. Provide translators with audio reference files so they hear the original delivery
+3. Translators produce adapted scripts that match lip-sync timing where possible
+4. Casting directors in each territory audition actors against original character profiles
+5. Record in professional studios with game audio direction (context, emotion, pacing)
+6. Integrate recorded audio, verify lip-sync, QA dialogue triggers
+
+### Culturalization
+
+Culturalization goes beyond translation to address cultural sensitivities:
+
+**Content to review:**
+- **Gestures**: Thumbs-up is offensive in parts of the Middle East; the OK hand sign is offensive in Brazil
+- **Colors**: White symbolizes death/mourning in East Asia; red symbolizes luck in China but danger in Western cultures
+- **Symbols**: Religious symbols, national flags, and political imagery require careful handling — some are legally restricted (German anti-Nazi laws, Chinese content restrictions)
+- **Numbers**: 4 is unlucky in East Asia (sounds like "death" in Mandarin/Japanese); 13 is unlucky in Western cultures
+- **Historical references**: Colonial, wartime, and territorial references can provoke strong reactions — consult regional specialists
+- **Body exposure**: Standards vary drastically; Middle Eastern and Chinese markets have stricter modesty requirements
+- **Gambling imagery**: Loot boxes, slot machines, and gacha mechanics face legal restrictions in Belgium, Netherlands, and increasingly other markets
+
+**Rating board variations:**
+- A game rated T (Teen) by ESRB may receive a different rating from PEGI, CERO (Japan), or GRAC (Korea) based on cultural sensitivity differences
+- Blood color (red vs green), alcohol references, and sexual content have different thresholds per region
+- Some markets require a separate content review authority (China's NPPA approval process can take 6+ months)
+
+### Linguistic Quality Assurance (LQA)
+
+LQA is dedicated testing of every localized build, performed by native speakers who are also gamers.
+
+**LQA methodology:**
+
+```
+Phase 1: Text-in-context review (3-5 days per language)
+  - Play through the entire game in each language
+  - Flag: truncation, overflow, missing translations, placeholder errors
+  - Flag: tone/register mismatches (formal where casual is needed)
+  - Flag: inconsistent terminology (same item called different names)
+  - Flag: gender/number agreement errors in gendered languages
+
+Phase 2: Audio review (2-3 days per dubbed language)
+  - Verify all VO lines trigger correctly
+  - Check lip-sync alignment
+  - Flag mispronunciations of character/place names
+  - Verify subtitle-to-audio synchronization
+
+Phase 3: Functional review (1-2 days per language)
+  - Test text input (player names, chat) in each language's character set
+  - Test sorting (alphabetical order differs: Swedish å comes after z)
+  - Test date/time/number formatting (DD/MM vs MM/DD, comma vs period decimal)
+  - Test currency formatting ($1,000.00 vs 1.000,00 €)
+
+Phase 4: Culturalization review (1-2 days per region)
+  - Review all visual content (textures, UI art, cutscenes) for cultural issues
+  - Verify map/territory representations do not trigger geopolitical disputes
+  - Check that monetization flows comply with local regulations
+```
+
+**Bug severity for localization:**
+- **Critical**: Game crashes due to localization data; hard-coded English blocks progression
+- **Major**: Truncated text hides gameplay information; wrong translation changes meaning
+- **Minor**: Awkward phrasing; inconsistent but understandable terminology
+- **Cosmetic**: Slightly imperfect formatting; minor spacing issues
+
+### Pseudo-Localization for Early Testing
+
+Before real translations are available, use pseudo-localization to catch localization bugs during development:
+
+```
+Original:  "Health: {0}/{1}"
+Pseudo-FR: "[Ĥéåļŧĥ: {0}/{1}        ]"
+Pseudo-AR: "[‫صحة‬: {0}/{1}]"  (with RTL marker)
+Pseudo-JP: "[ヘルス: {0}/{1}]"
+```
+
+Pseudo-localization rules:
+- Replace ASCII characters with accented Unicode equivalents (catches encoding bugs)
+- Expand string length by 30-40% with padding (catches truncation bugs)
+- Wrap strings in brackets `[...]` (catches hardcoded strings that were not externalized — they will not have brackets)
+- Add RTL markers for Arabic pseudo-loc (catches layout mirroring issues)
+
+Run pseudo-localized builds in CI. If any UI element overflows, truncates, or displays raw string IDs, the build should warn. This catches 80% of localization bugs before a single translator touches the project.