PRD-038 · Glossary: the site's technical terms, one sentence each

Status · Shipped on tech-debt/phases (2026-10-31), plan approved by the operator in session Date · 2026-10-31 Owner · Marko Builds on · scripts/i18n-tools/native-terms.json (term section, the space-terms pilot) · docs/wip/2026-10-31-space-terms-glossary-pilot.md · /sourcing (a small data-driven page) · PRD-037 (the sibling page for names) · RFC-011 OQ-4 (the deferred A–Z science lookup)

Why this is a PRD. It adds a public route built from an internal translation tool. It promises readers one word per term on every page, and the term gate in CI keeps that promise.

1 · What

/science/glossary: a page like the glossary at the back of a technical book. For every technical term in the glossary's term section (20 at launch: orbit, trajectory, burn, flyby, orbit insertion …), in the reader's language:

• the term, sorted alphabetically in that language;
• a one-sentence definition;
• Read more: the /science page that explains it (18 of 20; rendezvous and payload have none);
• Used on: the pages that use the term most (up to 5).

Each entry has an anchor (/science/glossary#gravity-assist) for deep links.

Where it lives: a "see also" tab of /science, next to Reading List and Watch List (operator, 2026-10-31). The terms are the science section's vocabulary: every definition but two points to a science article, and the articles mostly explain these terms. Missions, fleet and essays use them without explaining them, and the "used on" links show that use. Also linked from the footer, the phone drawer and the end of the /science landing.

2 · Data path

• Terms and forms: native-terms.json term (binding form per locale; _read_more names the science page).
• Definitions: overlays i18n-src/<locale>/glossary/terms.json, translated like any overlay. They are checked by problems() and by the term gate, so the definitions use the binding forms. They live in their own i18n chunk (glossary), so no other page loads them.
• Build: scripts/build-glossary.mjs (in npm run build) writes static/data/glossary/<locale>.json, one file per locale. It resolves names, definitions, the read-more page and the "used on" pages with their titles. "Used on" is counted on the English text, the way term-drift.mjs finds a term. The output is generated and gitignored.
• A term added to the glossary (with its definitions) appears on the page; no code change.

3 · Guards

• scripts/build-glossary.test.ts:
  • every term has a definition in all 14 locales (no English fallback) and a title for every linked page;
  • the science, essay and program links exist;
  • the route mapping is tested.
• The term gate (term-glossary.test.ts) covers the definitions (glossary tree).
• check-internal-links (build) checks every rendered link, and the a11y gate includes /science/glossary.

4 · Relation to other pages

• PRD-037 (/names, draft): the same glossary file, for names. Separate pages, because names and terms follow different rules (origin rule vs. native terms).
• RFC-011 OQ-4: the deferred alphabetical science lookup. /science/glossary covers the technical vocabulary, and each entry links to its science page. A flat /science/all list of every section is still not built.

5 · Later: terms linked from the text

The last item of the planned work (operator, 2026-10-31). The first mention of a glossary term in an article links to its entry (/science/glossary#gravity-assist), closing the loop in both directions. It needs a rule for which mention to link and care in 14 languages (inflected forms match through the glossary's stems), so it comes after the next term batch.

5b · Later still: a small visual per term (operator idea, 2026-10-31)

After the term links, the final item. Each entry gets a small visual in the style of the science pages' diagrams, because a picture helps with the concept: apogee/perigee on an ellipse, a burn as a thrust arrow on an orbit, a gravity-assist bend, staging, the entry corridor. It uses the house pipeline in docs/guides/diagram-art-style.md (precise SVG sketch → Higgsfield nano_banana_pro → webp) so the glossary and /science read as one hand, and it reuses a science page's diagram where one already shows the term. Generation spends Higgsfield credits: count the terms, estimate the credits and get a go before running.

6 · Non-goals

• Definitions for every science page. Only the glossary's terms appear here.
• Search on the page: 20 entries; site search (Cmd-K) covers lookup. Revisit at ~100 terms, and add an A–Z jump bar then too.
• Per-locale "used on" counts: the pages are the same in every locale, so the counts come from the English text.