PRD-007 — Multi-Language Support
Orrery · Product Requirements · v0.1 · May 2026
Status: Draft Depends on: RFC-010 (open — must close before implementation begins) Slice: v2.0 Screens affected: All (cross-cutting) Principles: physics first, attribution is design (PA §principles) Why this is a PRD · Translation is the single highest-leverage action to expand reach: ~3B speakers are excluded by English-only state. The architecture is already in place (ADR-017); this PRD defines what "shipped in language X" means in terms of UX, terminology accuracy, and acceptance gates so a translation pass for any locale has a clear bar to clear.
§why
Space exploration is a global endeavour. The simulator's current English-only state excludes the majority of the world's space agencies' home audiences — including the 1.1B Mandarin speakers watching CNSA's Tianwen missions, the 600M Hindi speakers following ISRO's Chandrayaan and Gaganyaan programmes, and the hundreds of millions of Spanish and French speakers engaged with ESA and Latin America's growing space sector.
The i18n architecture is already in place. This PRD defines what the user-facing translation experience looks like, and what "done" means for each language added.
§audiences
This feature serves all three existing audiences, with additional reach into new populations:
The curious learner — now reached in their native language. A student in Mumbai, a teacher in São Paulo, a teenager in Tokyo — all currently excluded. Translation is the single highest-leverage action to expand this audience.
The STEM student — particularly served by accurate physics terminology in their language. A Japanese student who already knows what a ホーマン遷移軌道 (Hohmann transfer) is should see that term, not a transliteration.
The space enthusiast — the community of people who follow JAXA, CNSA, ISRO, DLR, and Roscosmos missions. These people are deeply knowledgeable; translation quality matters. Errors in orbital mechanics terminology will be noticed and will damage credibility.
§promises
The simulator makes these promises to a user in a non-English locale:
- The full experience is available in their language. No screen, panel, or label falls back to English mid-session.
- Physics terminology is accurate. Terms like "Hohmann transfer", "delta-v", "Tsiolkovsky equation", and "porkchop plot" are rendered using the accepted convention in that language's scientific community — not machine-translated literally.
- The locale is shareable. Switching language updates the URL
?lang=parameter so the choice is bookmarkable and copy-pasteable. (Cross-session persistence via storage is intentionally not promised — see CLAUDE.md "do not use localStorage" rule.) - Switching language is effortless. A language picker is accessible from every screen in one interaction.
- No content is hidden. All 32 missions in the library, all configurator parameters, all HUD labels, all fact panels — translated.
§language-picker UX
A language selector is added to the navigation bar (right side, before the existing controls).
Behaviour:
- Displays the current locale as a short label (e.g.
EN,ES,日本語,中文,عربي) - On click/tap: opens a dropdown listing all available locales by their native name (not English name)
- e.g.
Español,Français,Deutsch,日本語,中文（简体）,हिन्दी,Português,العربية,한국어,Русский,Italiano
- e.g.
- Selection takes effect immediately — the URL is updated to
?lang=<code>so the navigation re-renders without a full reload - The URL
?lang=parameter is the single source of truth; nolocalStorage/sessionStorage(per CLAUDE.md) - On first visit (no
?lang=in URL): browser locale is detected vianavigator.language; if a supported locale matches, the URL is rewritten viareplaceStateto?lang=<code>; otherwise falls back to English
RTL handling:
- When Arabic is active,
<html dir="rtl">is set - All UI chrome mirrors correctly (nav, panels, bottom bar)
- Three.js canvas and 2D plots are direction-neutral and unaffected
§string scope
All translatable strings are in the existing locale files. For reference, the categories are:
| Category | Examples | Approx. string count |
|---|---|---|
| Navigation labels | Explorer, Configurator, Mission Arc, Library, Earth, Moon | ~20 |
| Configurator controls | Launch window, Payload mass, Engine type, Departure date | ~60 |
| HUD labels | Velocity, Distance from Earth, Signal delay, Mission elapsed | ~40 |
| Mission metadata | Mission names, agency names, destination labels, status | ~120 |
| Fact / editorial text | Body descriptions, mission summaries, capability callouts | ~800 |
| Error / status messages | Loading, no result, out of range, worker failed | ~30 |
| Accessibility labels | ARIA labels on all interactive controls | ~80 |
| Total | ~1,150 strings |
Physics terms (delta-v, Isp, Hohmann, porkchop plot, etc.) must use the accepted scientific convention in each target language, not a literal translation. See §translation-guidance below.
§translation-guidance
Translators must be briefed on the following before beginning work:
Terms to use by scientific convention (do not translate literally):
| English term | Notes |
|---|---|
| Delta-v (Δv) | Use the symbol universally; add native-language gloss in first use only |
| Hohmann transfer | Proper noun — do not translate; transliterate only if no established usage |
| Isp (specific impulse) | Use abbreviation; add native gloss |
| Porkchop plot | Established term in mission planning; may be translated or transliterated per convention |
| Tsiolkovsky equation | Proper noun — transliterate per convention |
| Aphelion / Perihelion | Established astronomical terms with accepted equivalents in most languages |
| C3 (characteristic energy) | Use symbol universally |
| SOI (sphere of influence) | Translate the concept; use established equivalent |
| Astronomical Unit (AU) | Use UA in Spanish/French/Portuguese; AU elsewhere |
Mission and agency names: Use the official romanisation / official native-language name as published by the agency itself.
- e.g. CNSA publishes 天问 (Tianwen) in Chinese and Tianwen in English — use both
- e.g. JAXA uses はやぶさ (Hayabusa) — use the official romanisation for non-Japanese locales
Number formatting: Respect locale conventions.
1,000,000km (EN) →1.000.000km (DE) →1 000 000km (FR)- The i18n layer handles this via
Intl.NumberFormat— translators do not need to format numbers in strings
§language rollout
Phasing is subject to RFC-010 resolution. Proposed waves:
Wave 1 — v2.0 (Latin script; lower implementation risk)
| Language | Locale code | Primary space agency served |
|---|---|---|
| Spanish | es | ESA contributors; Latin America |
| French | fr | CNES, ESA |
| German | de | DLR, ESA |
| Portuguese (BR) | pt-BR | AEB (Brazil) |
| Italian | it | ASI, ESA |
Wave 2 — v2.1 (CJK scripts; requires font strategy from RFC-010 OQ-2)
| Language | Locale code | Primary space agency served |
|---|---|---|
| Mandarin (Simplified) | zh-CN | CNSA, CMSA |
| Japanese | ja | JAXA |
| Korean | ko | KARI |
Wave 3 — v2.2 (non-Latin, non-CJK; requires RTL audit for Arabic)
| Language | Locale code | Primary space agency served |
|---|---|---|
| Hindi | hi | ISRO |
| Russian | ru | Roscosmos |
| Arabic | ar | UAESA |
§definition-of-done (per language)
A language is considered done when all of the following are true:
- [ ] All ~1,150 strings translated and reviewed by a native speaker with science/technical background
- [ ] Physics terminology verified against the accepted convention for that language
- [ ] All 6 screens render correctly with no truncation, overflow, or layout breaks at the translated string lengths
- [ ] Language picker shows the language in its native name
- [ ] Locale is shareable via URL
?lang=(no storage; first-visitnavigator.languagedetection rewrites the URL) - [ ]
prefers-reduced-motionbehaviour unchanged in the new locale - [ ] All ARIA labels translated (screen reader accessibility maintained)
- [ ] For CJK: appropriate font loads correctly; no tofu (□) characters
- [ ] For RTL (Arabic): all UI panels mirror correctly; no content clipping
- [ ] Playwright e2e passes: language switch → all screens → no console errors
§what-is-deferred
- Locale-specific unit preferences (km vs miles) — separate ADR
- Regional mission data variation (e.g. showing CNSA-published mission data in Chinese locale) — future consideration
- Dubbing or narration (audio is out of scope)
- Locale-specific imagery or cultural adaptation (translation only; no asset changes)
- Right-to-left canvas layouts (canvas is direction-neutral; not applicable)
References
| What | Where |
|---|---|
| i18n architecture | docs/adr/ADR-017.md |
| Translation strategy RFC | docs/rfc/RFC-010.md |
| Accessibility spec | docs/rfc/RFC-005.md |
| Product authority | docs/prd/PA.md |
| v1.0 deferred list | docs/prd/PRD-006.md §deferred |
| ROADMAP | ROADMAP.md |