ADR-044 — CJK font strategy for Wave 2 locales
Status · Accepted Date · 2026-05-06 Supersedes in part ·
docs/adr/ADR-032.md(Wave 2 CJK deferred note) Scope ·zh-CN,ja,ko
Context
Issue #37 schedules Wave 2 locale rollout for Simplified Chinese (zh-CN), Japanese (ja), and Korean (ko). ADR-032 explicitly deferred the CJK font decision.
We need a decision that keeps bundle risk low while ensuring CJK glyph coverage does not regress readability.
Decision
For Wave 2, Orrery keeps its existing bundled typography and relies on platform font fallback for CJK glyph rendering.
No new bundled CJK font files are added in this rollout.
Rationale
- Avoids adding large CJK font payloads to every user's first paint.
- Preserves current visual identity (
Bebas Neue,Space Mono,Crimson Pro) where those fonts already apply. - Keeps Wave 2 implementation minimally invasive: locale plumbing and content overlays only.
- Matches ADR-017 fallback behavior and current static-site delivery constraints.
Consequences
Positive:
- Zero additional font bytes for non-CJK users.
- No changes required to asset fetch/preload pipeline.
- Wave 2 can ship immediately with low operational risk.
Negative:
- Typography can vary by OS/browser for CJK text because fallback stacks differ.
- Some headings may show mixed-font appearance when branded fonts lack CJK glyphs.
Alternatives considered
- Bundle per-locale Noto Sans fonts (SC/JP/KR): improves consistency, but adds significant payload and font-loading complexity.
- Bundle a single Noto Sans CJK family: one strategy for all CJK locales, but still large and costly for non-CJK traffic.
- Delay Wave 2 until dedicated CJK font pipeline lands: rejected; blocks locale rollout on non-critical styling work.
Implementation notes
- Add Wave 2 locales to
project.inlang/settings.json, runtime locale lists, messages, and data overlays. - Keep
?lang=as locale source-of-truth; no storage-based locale state. - If future UX requires stronger cross-platform CJK consistency, supersede with a dedicated font-loading ADR.