Skip to content

Add source-localized mdBook readers with SolidJS - #2

Closed
shixi-11 wants to merge 27 commits into
alux-network:masterfrom
shixi-11:feat/multilingual-reading-worlds
Closed

shixi-11 wants to merge 27 commits into
alux-network:masterfrom
shixi-11:feat/multilingual-reading-worlds

Conversation

@shixi-11

@shixi-11 shixi-11 commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Result

Adds an eleven-language ALUX Programming reading site with a forest entrance, a paginated magic book and a quiet document reader. Both worlds retain direct chapter entry, full contents, search, bookmarks, shared reading preferences, on-demand pagination with explicitly labelled chapter progress and reliable cached whole-book numbering, book/scroll modes, bounded video clips, welcome audio and reading music.

Content and application architecture

  • English chapters and one canonical SUMMARY.md remain authoritative. The 280 approved translated chapters now live beside them as chapter.<lang>.md; missing translations fall back to English.
  • A web-only mdBook preprocessor selects translated sources before normal includes, admonitions and KaTeX. Native mdBook JSON supplies structure and native HTML supplies rendered content. No frontend Markdown compiler is introduced.
  • Build-time content/<lang>.json models serve both readers, search and static routes. The browser loads only requested editions. Canonical chapter paths, heading IDs, reading storage and four legacy heading aliases are preserved.
  • SolidJS and strict TypeScript own navigation, language selection, dialogs, bookmarks and reader controls. One reactive edition owns locale/book/messages. Opaque chapter HTML and scoped pagination/PageFlip/audio adapters keep browser-specific work separate.
  • Explicit typed UI dictionaries and variable-message keys replace prose dictionaries, HTML-token alignment and runtime DOM text translation. Protected code, TeX, links, images and media attributes are validated before replacing reader JSON.

Original English Markdown, book.toml, the mdBook theme and the GitHub Pages workflow remain unchanged. No merge or production deployment is included.

Validation and handover

  • pnpm --dir web build and strict TypeScript pass; 36 Node unit/integration tests pass.
  • All 280 migrated chapter bodies match their frozen prior editions for visible text, code, TeX, links and media. One pre-existing Japanese heading-list metadata artifact is corrected to match the already-correct visible heading; its canonical ID is unchanged.
  • pnpm --dir web test:browser passes 318 assertions, including 99 language/viewport/route combinations across all eleven languages at 320/768/1440px, both worlds and contents, plus interaction regressions.
  • Delayed-font/image probes paint readable pages without an empty-book frame. Physical-device audio and live social crawler caches remain unverified.
  • Three independent scoped code reviews were completed; blocking findings were fixed and rechecked.

The existing GitHub Pages workflow is unchanged. A separate reader workflow now runs frozen installation, compiler lint/strict types, builds/tests, generated-route/resource audits, full-output repeatability and browser acceptance. Publishing still runs only on pushes to master; this PR does not deploy production. Latest CI status is reported in the PR checks rather than inferred from local tests.

The acceptance follow-up fixes current-chapter-only measurement, PageFlip resource cleanup, cancelled navigation/clipboard work, Windows mdBook support probes, mobile View Transition timing and duplicate embedded players in animation snapshots. English-source fingerprints provide non-blocking translation freshness warnings. Chromium, Firefox, Android-profile Chromium and iPhone-profile WebKit pass local automation, including native audio playback-clock/pause checks. These mobile profiles are simulations. The owner has Android but no iPhone/iPad; physical Android Chrome and iOS Safari remain NOT TESTED.

See measurable acceptance and remaining device limits for PASS/FAIL/NOT TESTED evidence, versions, commands, repeatability and the baseline comparison.

See the migration and review record, web maintenance instructions and local build/browser-test instructions. The reader and social preview pages remain under web/previews/.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ⚠️ Failed 2026-10-22T21:42:39.564030Z
We couldn’t complete this review. Comment @codex review to try again.
796fe1f PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

@shixi-11 shixi-11 changed the title Add multilingual dual-world readers, localized welcome audio and rebuilt previews Add multilingual dual-world readers, welcome audio and refreshed book illustrations Oct 23, 2026
@tgrospic

Copy link
Copy Markdown
Member

I like the new design with Magic world. It also shows that good specification can provide multiple implementations like here different UI interpretations.

To support this direction I suggest some reorganization of web project. It's standard JS tooling which can better integrate with mdbook that can provide structured data for SPA app. mdbook is like simple compiler or src content.

Below is the prompt for AI.


Architecture refactor requested: TypeScript + Vite + mdBook JSON

The new reader looks promising, but the implementation is becoming unnecessarily complex, particularly web/scripts/content.mjs.

We should not reimplement mdBook's content processing in JavaScript. mdBook already owns the book structure, chapter ordering, Markdown preprocessing, links, and extensions.

Please refactor the web/ project with these goals:

1. Single source of truth

Use mdBook's JSON renderer output as the input to the website build.

  • Add a custom mdBook JSON renderer backend that serializes the processed Book received from mdBook.
  • Preserve chapter hierarchy, titles, paths, content, and ordering.
  • Do not parse SUMMARY.md manually.
  • Do not reconstruct the book structure from filesystem conventions.
  • Preserve existing mdBook preprocessors, including admonish and KaTeX.
  • Use a well-defined, typed transformation from mdBook JSON to the reader's content model.

Note: mdBook JSON contains chapter Markdown, not rendered HTML. Use a Markdown renderer only for the remaining rendering step. Do not duplicate preprocessing or assume the JSON provides a Markdown AST.

2. TypeScript + Vite

Convert the web/ application and build scripts to strict TypeScript, using Vite for development and production builds.

Suggested minimal structure:

web/
  index.html
  package.json
  tsconfig.json
  vite.config.ts

  scripts/
    book.ts            # mdBook JSON -> reader data

  src/
    main.ts            # application entry
    book.ts            # typed book model
    reader.ts          # shared reading behavior
    navigation.ts      # routing, TOC
    i18n.ts            # localization
    rendering.ts       # Markdown/HTML presentation
    styles/            # existing styles

  public/
    art/
    audio/
    fonts/

This is a guideline, not a requirement to create extra abstractions or files.

3. Separate content from presentation

The architecture should be:

Markdown + SUMMARY.md
         |
       mdBook
         |
   mdBook Book JSON
         |
  Typed transformation
         |
    Reader content
         |
    +----+----+
    |         |
 Magic UI   Real UI

Both reading experiences must consume the same content model. Neither should know how mdBook or Markdown source files are organized.

Language variants must preserve the same structural chapter identity, heading anchors, code, equations, and source links.

4. Eliminate duplicated logic

Replace or simplify content.mjs, particularly:

  • Manual SUMMARY.md parsing.
  • Custom heading slug and anchor generation that can diverge from mdBook.
  • Reimplementation of admonish and math preprocessing.
  • Hardcoded Markdown link and image rewriting.
  • Repeated content transformations embedded in rendering logic.

Keep genuine reader-specific behavior, such as video clip presentation, syntax highlighting, navigation, and book pagination, in small, focused modules.

Use mdBook-compatible rendering and anchor rules rather than inventing another Markdown dialect. Where mdBook JSON does not supply the required representation, make that transformation explicit and test it.

5. Build pipeline

Provide simple commands:

pnpm dev
pnpm build
pnpm preview
pnpm test

pnpm build should generate the mdBook JSON, transform it to reader data, type-check, and build the static website with Vite.

pnpm dev should rebuild reader content when the book Markdown changes, preferably with live reload.

Keep GitHub Pages deployment straightforward. No server runtime.

6. Preserve behavior

Do not redesign the UI as part of this refactor.

Preserve the existing languages, two reading modes, audio, search, bookmarks, pagination, math, admonitions, artwork, routes, and responsive behavior.

Add focused tests for chapter hierarchy, links, heading anchors, translation alignment, and preservation of code and mathematical expressions.

Main principle: mdBook defines the book. TypeScript defines a minimal typed reader model. Vite builds the UI. Presentation must not become another book compiler.

Please implement the refactor, not just propose an architecture. Favor a small, readable, dependency-light project over framework complexity.

@shixi-11 shixi-11 changed the title Add multilingual dual-world readers, welcome audio and refreshed book illustrations Add multilingual readers backed by mdBook and strict TypeScript Oct 23, 2026

Copy link
Copy Markdown
Contributor Author

Thanks, @tgrospic. Implemented the refactor in this PR.

  • mdBook now supplies the processed Book JSON, preserving order, hierarchy, paths and part titles. The manual SUMMARY parser and custom Markdown/preprocessor implementation are gone.
  • Because Book JSON still contains Markdown, the same build uses mdBook's native HTML renderer for that final step. This keeps native heading IDs, links, admonish and KaTeX behavior; TypeScript adapts only the reader presentation.
  • Both readers use the same typed model and localization function. All 1,832 existing prose units align with native output without rewriting the dictionaries. Four legacy heading fragments remain compatible aliases.
  • The app and build scripts are strict TypeScript, with Vite and documented dev/build/preview/test commands. Markdown changes rebuild and reload; failed content checks retain the last successful reader data.
  • Existing interfaces and features are retained. The sharing wordmark also now matches the reader sidebar's font roles and proportions.

Validation: build and strict type checks pass, with 33 unit/integration tests; 1,881 page-number/code checks across all 28 chapters, eleven languages and three widths; 264 reader interaction checks; and 739 sharing checks. The previous reader's 77 code blocks, 95 equations and four video addresses are preserved. The original source book and publishing workflow are unchanged.

The implementation and setup details are in web/README.md. Ready for another review.

Copy link
Copy Markdown
Contributor Author

Fixed an intermittent blank-book regression in 6ae6444.

When image decoding was still pending, navigating to another chapter and resizing could leave an old reader's resize callback alive. It queried the shared app for #page-book, acquired the new chapter's element, and later removed it during cleanup. Pagination now acquires only its own connected volume, and detached/disposed readers cannot update pages, keyboard navigation, anchors or footer state. Pending animation-frame callbacks also check the pagination revision. Empty-fragment history navigation no longer creates an invalid selector.

Reproduced the missing book element before the fix; the identical delayed-image/navigation/resize sequence now retains the new chapter in both development and the production preview. Build/type checks and all 37 unit/integration tests pass, including four new ownership regressions. Another 60 browser checks pass with normal animations across English, Chinese and Arabic, light/dark themes and 390/1600px widths, covering rapid turns, font changes, anchor jumps and browser history.

Comment thread web/public/art/alux-bronze-night.png Outdated

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please resize these big images to needed size. Git repo behaves much better with smaller files and it's optimized for text. So images should be used carefully.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, @tgrospic. Addressed in 2e54da9.

  • Removed 13 unused PNG masters from the tracked public tree after preserving identical originals separately. The current public/art directory is now 3.04 MB instead of 29.09 MB.
  • Resized the runtime marks to 256×239, the ribbon to 256×704 and the crab to 512×512. The night mark is now 30,408 bytes instead of 199,680; these four runtime assets together dropped from 962,870 to 165,900 bytes.
  • Checked the actual rendered sizes at 3840×2160/DPR 1 and 1920×1080/DPR 2 in both themes. Small artwork retains enough resolution for its display size, with complete subjects, proportions and transparency. The forest, standing wizard and full-width textures retain their native dimensions; no upscaled artwork is being described as native 4K.

The unused PNGs were not page requests, so their removal primarily reduces the checkout/static artifact; the runtime reductions also reduce image transfer. Earlier binary blobs remain in Git history, which I have not rewritten. Asset sizing and maintenance notes are in web/ARTWORK.md.

@tgrospic tgrospic added the enhancement New feature or request label Oct 23, 2026

Copy link
Copy Markdown
Contributor Author

Follow-up in 2e54da9 also fixes the blank paper shown during refresh and initial pagination.

The current chapter now appears as readable sheets before image/font preparation and whole-book counting finish. Reflow keeps the existing content, and a noninteractive visual copy bridges PageFlip's first paint without duplicate anchors or active embedded players. Fonts and images prepare concurrently; decoded images are reused between chapters, and scroll mode no longer preloads every book illustration.

The page-number audit also caught lazy illustrations measuring differently before their intrinsic size was available. Their reserved dimensions and display boxes are now stable, so cached chapter offsets match the rendered pages.

Validation: production build/strict type checks and 39 unit/integration tests pass; 1,881 numbering/code checks across all 28 chapters, eleven languages and three widths; 72 delayed-image/font cold-load, reload and reflow checks; 12 pagination-state checks; 48 artwork checks; and 20 checks at 4K viewport/high-density display sizes. The frame-by-frame checks found no empty book frame. In the local production preview, readable content appeared at about 0.73s cold and 0.25s on reload, while complete pagination continued in the background. Public-network timings have not been measured.

The image-sizing changes are detailed in the reply to your inline review. The source book and publishing workflow are unchanged.

shixi-11 commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor Author

@tgrospic, added a site-identity follow-up in 0ac51cc.

The tab icon now uses the verified official ALUX mark in warm gold on a forest-green badge, with no miniature bronze texture. The self-contained SVG is under 10 KB, with PNG/ICO fallbacks and a touch icon; a new favicon URL avoids the previous cached icon.

Browser titles, app names and Open Graph site names now have Chinese and English treatments: the two Chinese editions use their Chinese name, and all other language editions use “ALUX Programming.” Chapter titles, body translations, descriptions and existing language-specific covers remain localized. Static routes, runtime navigation and the sharing preview agree.

Production build, strict type checks and all 40 tests pass. Another 678 static/live branding checks pass across all eleven languages and both readers, including a language switch, preview site names and served icon variants. The icon was also inspected at 16/32px, on light/dark surfaces and at DPR 2. The source book and deployment workflow are unchanged.

Earlier updates in this PR: navigation and blank-book lifecycle fix, refresh/loading and page-number corrections, and image sizing and high-density display checks.

Cache search text per localized book and update only search results. Index canonical translation blocks with nested-content invalidation, and reuse preview sheets when layout counts are already settled. Preserve output, page numbering and animation behavior.

Copy link
Copy Markdown
Contributor Author

@tgrospic, a focused reader-performance follow-up is now in 87442d8.

  • Search caches lowercase titles/text per localized book and updates only the results container. It no longer retranslates the entire document or refreshes every icon on each keystroke; matching, ranking, snippets and destination URLs are preserved.
  • Translation matching indexes canonical HTML once per chapter, preserves document order for duplicate blocks, and rebuilds after nested-block changes. Whole-book block scans drop from 1,832 to 68 without changing any translated chapter data.
  • With an already settled layout, chapter navigation reuses the freshly paginated preview sheets instead of paginating the same chapter twice. Cold layouts still wait for fonts/images and calculate the full continuous page numbering. The existing 560ms page animation is unchanged.

In an interleaved local Chrome test with 4× CPU slowdown, median search-handler time changed from 12.7→4.7ms (English), 14.7→4.3ms (Chinese) and 16.5→4.6ms (Arabic), with 60 measured inputs per version/language after warm-up. A second, noisier batch confirmed the direction. These measure local CPU work; English startup improvement was inconclusive, so I am not claiming a general network-loading speedup.

Validation: production build, strict types and all 44 tests pass; 280 translated chapters are exactly equal to the prior implementation; all 300 search-result/URL comparisons match. Also reran 1,881 page-number/code checks, 529 search interactions, 72 delayed-load/reload checks, 12 pagination-state checks and 60 normal-animation lifecycle checks. Three desktop/mobile/RTL search screenshot comparisons are pixel-identical. The maintenance notes document cache invalidation and the settled-layout requirement.

Copy link
Copy Markdown
Contributor Author

@tgrospic, the maintenance-guide follow-up is in 8d1397b.

web/AGENTS.md now specifies the localized page title followed by exactly one site-brand suffix, the Chinese/English brand mapping, the chooser's shorter tab title versus its full sharing title, and the required favicon variants. It also calls for checking static loads, refreshes, client-side navigation and language changes in both reading worlds whenever identity metadata changes.

An audit of all 737 generated HTML pages found that the current titles already follow these rules. This commit documents the existing behavior; it does not change the reader UI, book content or deployment workflow. The root AGENTS.md remains the tracked entry point to the detailed reader guidance.

Copy link
Copy Markdown
Contributor Author

@tgrospic Browser-icon polish is now in 9df15cc: the official mark has more breathing room (44 units within a 64-unit canvas), with a restrained warm-gold gradient and a deep-forest background. The SVG, 16/32/48px ICO, 32px PNG and touch icon are synchronized, and the icon URL version was bumped to refresh cached tabs.

Validation: the production build and strict TypeScript checks passed; all 737 generated pages reference the updated icon. I checked 16px and 32px rendering on light and dark backgrounds. CI is green: https://github.com/alux-network/alux-programming/actions/runs/40014693966.

@tgrospic

Copy link
Copy Markdown
Member

Refactor multilingual content: Markdown translations as first-class mdBook sources

The TypeScript and mdBook JSON integration are much better now. However, translation is still implemented through a complex HTML-token alignment system and runtime DOM manipulation.

We should simplify the architecture rather than continue extending this machinery.

Goal: every language should have real Markdown source files, processed by mdBook before rendering. The frontend should only consume already-localized book data.

Please implement the following refactor.

1. Translation sources: chapter.<lang>.md

Keep English as the canonical source and introduce optional per-language Markdown files alongside each chapter.

Example:

src/
  SUMMARY.md
  introduction.md
  introduction.zh.md
  introduction.de.md
  introduction.es.md

  design/
    capabilities.md
    capabilities.zh.md
    capabilities.de.md

Use the existing supported language codes:

en, zh, zh-hant, ko, ja, ar, vi, ru, uk, de, es

Naming rules:

  • chapter.md is the canonical English source.
  • chapter.<lang>.md is the translated source.
  • Preserve the existing chapter hierarchy and paths.
  • Do not create eleven copies of SUMMARY.md.
  • Do not infer chapter ordering from filenames.
  • Preserve a stable canonical chapter ID across languages.
  • Missing translations must fall back to the original English Markdown.

Keep translation files next to their originals so content changes and translations are easy to review together in Git.

2. Reuse mdBook, do not implement another Markdown processor

The current scripts/mdbook.ts already builds mdBook JSON and HTML outputs. Extend this existing pipeline rather than creating a parallel one.

Implement a small translation preprocessor that:

  1. Receives mdBook's structured Book JSON.
  2. Reads the requested language from mdBook configuration.
  3. For each chapter, resolves its canonical source path.
  4. Checks for a matching .<lang>.md file.
  5. Substitutes the translated Markdown when available.
  6. Preserves canonical chapter identity and chapter ordering.
  7. Allows mdBook to perform its normal processing and rendering.

Configure preprocessor ordering correctly so Markdown includes, links, admonitions, KaTeX, and other existing features remain supported.

Use mdBook's documented preprocessor protocol, including the appropriate renderer support.

Avoid editing SUMMARY.md or copying translated files over English originals.

3. Keep the existing dual-output design

The pipeline should be:

Canonical SUMMARY.md
         +
  English Markdown
         +
  Localized Markdown
         |
         v
  mdBook preprocessing
         |
         v
   Localized Book
      /       \
     v         v
  Book JSON  mdBook HTML
      \       /
       v     v
 Typed ReaderBook
       |
       v
   Vite build
       |
       v
  Magic / Real

Keep the existing typed ReaderBook model as the shared representation.

Generate localized reader content at build time, for example:

content/
  en.json
  zh.json
  zh-hant.json
  ko.json
  ja.json
  ar.json
  vi.json
  ru.json
  uk.json
  de.json
  es.json

These are generated artifacts, not translation sources.

Both Magic and Real readers must consume the same localized data.

Avoid bundling all eleven language books into the initial JavaScript payload. Load the selected locale on demand.

4. Eliminate runtime chapter translation

The current implementation uses:

  • web/scripts/translation-alignment.ts
  • web/locales/manifest.json
  • web/locales/source.json
  • per-language translation dictionaries
  • HTML token matching and reconstruction
  • runtime localized HTML transformations

These should no longer be necessary for chapter translation once translations are part of the Markdown source pipeline.

In particular, eliminate the need to tokenize generated HTML to identify translatable paragraphs, recover protected markup, and reconstruct translated HTML.

src/i18n.ts should primarily manage the selected language, loading localized content, persistence, and route generation.

Chapter localization must not traverse or rewrite the rendered DOM.

Remove translateUI(document) style translation of arbitrary text nodes and attributes. This includes the current TreeWalker, translation WeakMaps, and DOM-based text replacement.

Do not remove code simply because it looks related to translation. Migrate functionality first, then remove obsolete implementations.

5. Migrate existing translations without losing content

The PR already contains translations for eleven languages. We must preserve that work.

Create a one-time migration that converts existing translated chapter content from JSON dictionaries into chapter.<lang>.md files.

Requirements:

  • Preserve approved translated prose and chapter titles.
  • Preserve code blocks exactly.
  • Preserve inline code, links, images, mathematical expressions, and technical identifiers.
  • Preserve admonitions and their structure.
  • Keep canonical chapter links functional.
  • Preserve heading anchor compatibility.
  • Preserve the distinct interview video references and playback ranges.
  • Do not automatically translate or rewrite technical examples.

Prefer Markdown-native content over HTML token placeholders.

Where conversion cannot be performed unambiguously, report the affected chapter and translation rather than silently producing incorrect Markdown.

After migration, the Markdown files become the source of truth. Translation dictionaries must not remain as a second authoritative content store.

6. Stable navigation and anchors

Language must affect presentation, not chapter identity.

For example:

/en/design/capabilities.html
/de/design/capabilities.html
/zh/design/capabilities.html

All three routes should refer to the same canonical chapter.

Preserve chapter identity, bookmarks, and reading position when switching languages.

Localized headings should have translated visible text but stable canonical anchor IDs whenever possible.

For example:

English: #composition
German:  #composition
Chinese: #composition

Do not generate unrelated anchors from localized heading text.

Implement this during build-time Markdown processing or via an explicit heading mapping, not through runtime DOM repairs.

Existing fragment links must remain valid.

7. Separate UI translation from book translation

Keep a small translation mechanism for interface strings such as:

  • Navigation labels
  • Search controls and messages
  • Settings
  • Bookmarks
  • Reader actions
  • Language selection
  • Accessibility labels

A typed UI locale dictionary is sufficient.

For example:

interface UiMessages {
  search: string;
  bookmarks: string;
  contents: string;
  settings: string;
}

Components should reference explicit message keys, not rely on scanning rendered English text.

Avoid translating arbitrary strings based on their current DOM text.

Book content belongs in Markdown. UI text belongs in UI locale dictionaries.

8. Use declarative UI state

The current main.ts and reader implementations still construct large HTML strings, assign innerHTML, and coordinate state using direct DOM manipulation.

Please improve this as part of the refactor.

Use SolidJS + TypeScript + Vite for the application UI, keeping the architecture small.

  • Navigation, dialogs, menus, bookmarks, and language selection should be declarative components.
  • Shared reader state should be reactive.
  • Switching languages should load a new localized book and update component state.
  • Do not patch already-rendered DOM text to change language.
  • Keep mdBook-generated chapter HTML opaque where possible.
  • Isolate pagination measurement and page-flip animation behind small imperative adapters.

Solid is not intended to replace browser layout measurement. Pagination and page flipping legitimately require some low-level DOM operations.

The important distinction is that presentation mechanics may manipulate their own DOM, while application state and translation must not depend on DOM inspection.

Do not wrap the existing DOM manipulation in Solid components and call that a refactor. Simplify the underlying model.

9. Simplify the project structure

Aim for a small structure such as:

web/
  scripts/
    mdbook.ts
    book.ts
    localization.ts

  src/
    main.tsx
    app.tsx
    book.ts
    i18n.ts
    state.ts

    components/
      MagicReader.tsx
      RealReader.tsx
      Navigation.tsx
      LanguagePicker.tsx

    pagination.ts
    page-turn.ts

  locales/
    ui/
      en.json
      de.json
      ...

This is a conceptual layout. Reuse existing modules where appropriate.

Do not introduce a framework-like layer of factories, registries, adapters, services, and managers for straightforward operations.

Prefer a few cohesive, typed modules with clear responsibilities.

10. Build and validation

Keep simple commands:

pnpm dev
pnpm build
pnpm test

The build must:

  1. Run the existing mdBook pipeline for each supported language.
  2. Generate localized Book JSON and HTML.
  3. Transform them into typed reader data.
  4. Validate chapter identity, navigation, and links.
  5. Build the static application using Vite.

Development mode should rebuild affected localized content when Markdown changes.

Preserve the existing GitHub Pages publishing behavior until deployment is intentionally changed.

Add tests for:

  • Correct language file selection.
  • English fallback for missing translations.
  • Identical chapter hierarchy across languages.
  • Canonical anchors and cross-chapter links.
  • Exact preservation of Rust code and technical identifiers.
  • Math and admonition rendering.
  • Arabic RTL layout.
  • Search results in the selected language.
  • Bookmark and reading-position continuity.
  • Both Magic and Real reading modes.
  • Existing media and page-turn behavior.

Retain the existing extensive visual and pagination regression tests where useful.

11. Acceptance criteria

This refactor is complete when:

  • A new translation can be added by creating chapter.<lang>.md, without manually modifying translation manifests or HTML token maps.
  • Editing a translated Markdown file changes only that language's generated content.
  • Missing translations use the canonical English source.
  • Both readers consume one common typed content model per language.
  • UI language switching does not inspect or translate DOM text.
  • No second Markdown parser or book-structure parser is introduced.
  • No existing language, code example, formula, illustration, route, bookmark, or reader interaction is lost.
  • The original mdBook build continues to work.
  • The overall amount of custom translation machinery is substantially reduced.

Core architectural principle:

Markdown defines content. mdBook processes it. TypeScript models it. Solid presents it. Vite builds it.

Translation is a source-level concern, not a DOM transformation problem.

Please implement this incrementally, verify migration against the existing translations, and remove superseded complexity. The result should be simpler and smaller than the current implementation, not merely divided into more files.

@shixi-11 shixi-11 changed the title Add multilingual readers backed by mdBook and strict TypeScript Add source-localized mdBook readers with SolidJS Oct 26, 2026

Copy link
Copy Markdown
Contributor Author

@tgrospic, implemented the source-localization and Solid refactor from your review. The main change is in ac70ab9, with review fixes in aca4f04; current head is ba2274d.

  • The 280 approved translations are adjacent chapter.<lang>.md sources. One SUMMARY controls structure, missing files fall back to English, and a small mdBook preprocessor selects the edition before the normal includes/admonish/KaTeX pipeline.
  • Native JSON/HTML now produce a shared, already-localized model per edition. Both readers and static routes consume it; the browser requests only selected languages. The old prose dictionaries, token alignment and DOM translation passes are removed.
  • Solid owns navigation, dialogs, bookmarks, preferences and a single reactive locale/book/messages edition. UI labels use explicit typed keys. Pagination/PageFlip and native audio remain scoped adapters around opaque chapter HTML.

Validation: the web build and 32 Node tests pass; the production-build Chromium regression passes 318 assertions across 99 language/viewport/route combinations, including book/scroll switching, search, bookmarks, language/world continuity and slow-asset first paint. Migrated visible prose and protected technical content match the prior editions; one existing Japanese heading-list metadata artifact is documented and corrected without changing its visible heading or canonical ID.

The unchanged original mdBook/linkcheck PR workflow is green for ba2274d. English sources, book.toml and publishing behavior are preserved.

Migration evidence and review resolutions and the root/web Agent guides now describe the source layout and handover boundaries. Ready for your review.

@tgrospic

Copy link
Copy Markdown
Member

The architecture looks much better now. The mdBook pipeline, Markdown translations, typed content model, and SolidJS integration address my main concerns.

I don't think another major refactor is needed. Let's focus on measurable merge criteria.

1. Pagination and lifecycle

  • Opening a chapter must not paginate unrelated chapters.
  • Resizing, font loading, and language switching must produce correct page boundaries without duplicated or missing content.
  • Repeatedly switching chapters and reader modes must not accumulate event listeners, observers, timers, or detached DOM nodes.
  • Page-turn animations must complete or cancel cleanly when navigating away.
  • No visible layout corruption, clipped text, or broken code blocks at supported viewport sizes.

2. Translation correctness

  • All supported languages must build successfully.
  • Every localized edition must preserve canonical chapter IDs, hierarchy, navigation, and links.
  • Missing translations must fall back to English.
  • Code, mathematical expressions, images, and technical identifiers must remain intact.
  • Changes to English Markdown must identify potentially stale translations. A warning is sufficient; no need to block builds.
  • No runtime DOM-based translation or parallel translation source remains.

3. Reproducible builds

  • A fresh checkout must pass pnpm install --frozen-lockfile, pnpm build, and pnpm test.
  • Building twice from identical inputs must produce identical generated content, excluding explicitly nondeterministic metadata.
  • No manually generated or untracked files should be required.
  • Original mdBook publishing must still work.
  • All internal links, chapter anchors, and generated routes must resolve.

4. Browser acceptance tests

Test both Magic and Real readers on:

  • Desktop Chromium and Firefox.
  • Mobile Chrome on Android.
  • Safari on iOS.

Verify at least:

  • Chapter navigation and browser back/forward.
  • Language switching and English fallback.
  • Bookmarks and reading-position restoration.
  • Search in the selected language.
  • Math, code blocks, admonitions, tables, and images.
  • Page turning, viewport resize, and orientation changes.
  • Audio playback and interruption when navigating away.

5. CI and performance

  • TypeScript strict checking, linting, build, and automated tests must pass in CI.
  • No uncaught console errors during the acceptance scenarios.
  • No failed internal asset or content requests.
  • No significant performance regression compared with the current PR baseline.
  • Avoid eager loading or pagination of chapters that are not being viewed.

Merge decision

Required before merge:

  1. Clean, reproducible build and passing CI.
  2. Working navigation, localization, bookmarks, and search.
  3. No content corruption or broken links.
  4. No reproducible pagination or lifecycle bugs.
  5. Mobile Safari and Chromium smoke tests pass.

Can be follow-up PRs:

  • Lazy pagination optimizations beyond what is needed for responsive navigation.
  • More sophisticated translation freshness reporting.
  • Additional performance optimization without a demonstrated regression.
  • Further code cleanup that does not fix a concrete problem.

Please report each acceptance criterion as PASS / FAIL / NOT TESTED, with test commands and browser versions where applicable.

No more architectural rewrites. Fix blockers, document remaining limitations, and merge when the required criteria pass.

shixi-11 commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor Author

@tgrospic, the measurable-acceptance follow-up is pushed in 6e731f5, e40f09b and 3c8c4e9; 9857efb pins the CI runner (current head). No further architecture rewrite.

Criterion Status Evidence
On-demand pagination PASS Only the opened chapter is measured and its images decoded. The owner approved explicitly labelled chapter progress until complete exact-layout counts have been learned through actual visits; no eager/background whole-book measurement.
Layout, navigation and lifecycle PASS Size/orientation/mode changes preserve chapter text; canonical sections survive language changes. Back/forward interrupts turns cleanly. Fixed PageFlip's retained rAF/resize/init work, aborted restoration and deferred clipboard feedback. Five destroyed instances now leave 0 frames/0 listeners/0 hosts; warmed navigation counts remain stable. Animation snapshots no longer load duplicate embedded players.
Languages, fallback and technical content PASS Eleven native editions; canonical structure/anchors and protected code/math/media checks retained. Missing-source English fallback tested. Windows support probes and a translated-title guard prevent silent English-body/localized-UI mismatches.
Translation freshness PASS Canonical English fingerprints warn non-blockingly after edits. The 280 initial fingerprints change metadata only; they do not imply a fresh linguistic review or automatically acknowledge translations.
Clean build and repeatability PASS Isolated tracked Git checkout, frozen install, compiler lint/strict types, build and 36 tests. Every dist file has an identical repeat-build SHA-256 inventory.
Internal links/assets PASS 737 HTML pages, 11,594 links, 5,522 fragments and 3,784 resource references; no missing targets.
Desktop Chromium / Firefox PASS Chromium 156.0.8078.47 and Firefox 157.0. Existing regression: 318 assertions / 99 language-viewport-route cases; additional normal-motion, history, content, lifecycle and native-audio clock/pause checks.
Android Chromium profile PASS — simulation Pixel 7 profile on desktop Chromium; touch/viewport/orientation checks.
iPhone WebKit profile PASS — simulation iPhone 13 profile, Playwright WebKit 27.2. This is not physical iOS Safari.
Physical Android Chrome / iOS Safari NOT TESTED The owner has Android hardware but no iPhone or iPad; no phone is connected to this environment. Mobile checks here rely on simulation. The hardware merge gate remains open.
Original mdBook/linkcheck CI PASS Current-head publishing workflow; publishing was skipped for the PR. Original workflow unchanged.
Frontend CI PASS Pinned Ubuntu 24.04 reader workflow completed successfully: frozen install, compiler lint/strict types, 36 tests, full-output repeat hashes, internal links and all four browser configurations. CI engines: Chromium 156.0.8078.4, Firefox 157.0, WebKit 27.2.
Performance against ba2274d PASS Same Chrome, 1440×960, five fresh contexts: median final-ready 1445ms → 405ms, requests 27 → 16. Local comparison, not a production SLA.

Reproduction: pnpm install --frozen-lockfile, pnpm lint, pnpm typecheck, pnpm build, pnpm test, pnpm test:generated, pnpm test:browser, pnpm test:acceptance from web/, with the documented pinned mdBook/Playwright tools.

Acceptance ledger and limitations, root AGENTS.md, web/AGENTS.md and the build guide are synchronized. Three independent read-only review lenses found no remaining blocking code finding after fixes; these are not maintainer approvals. The latest four-profile run has zero uncaught exceptions or failed internal requests; the ledger retains the earlier intermittent WebKit embed-script observation and its attribution limit.

No merge, auto-merge or production deployment was performed.

@tgrospic

Copy link
Copy Markdown
Member

@shixi-11 thank you for the acceptance work. You answered every criterion with evidence, and the only open gate is physical-device testing, which was never in your hands. I said no more architectural rewrites, and I'm going back on that now. This is not because #2 failed the criteria.

While reviewing, I tried how small the same reader could be on plain mdBook: no SolidJS, no separate content model and no client-side routing. mdBook builds every language edition itself (book.toml overrides plus a small translation preprocessor), each chapter stays a normal mdBook page, and one TypeScript module adds the magic and real worlds on top. It came out at a fraction of the code, which matters more to me for long-term maintenance than the extra capabilities of an SPA (single-page app). That is #3. Your translations, UI labels, images, fonts and audio are all carried over.

Where #3 stands against the same criteria:

  • PASS: all 11 editions build; canonical paths, structure, links and anchors are verified against mdBook's own book; English fallback; code, math, media and links are preserved in every translation; stale-translation warnings; byte-identical repeat builds; strict TypeScript, build and tests in CI (npm run check, npm run build, npm test).
  • PASS, Chrome only: basic browser specs against the built site in headless Chrome: the gateway, page turns within and across chapters, right-to-left turning, the real world, the language picker, bookmarks, and every edition loading in both worlds without console errors or failed requests.
  • NOT TESTED: Firefox, WebKit and mobile profiles.

Two places where your work would move #3 forward the most:

  1. Design: feat: multilingual mdBook editions with magic and real reader worlds #3 reproduces your look closely but not pixel for pixel. Please compare and refine it. The PR description's section "Continuing the design" says where each part lives (template, theme/reader.css, web/reader.ts, public/) and how to run it (npm start, port 3478). AGENTS.md explains the rules the build and tests rely on.
  2. Browser coverage: your Firefox, WebKit and mobile-profile scenarios, added to web/test/browser.test.ts with the routes the site test already derives from mdBook.

You can continue here by rebasing this PR on top of #3, or open a new PR against #3's branch, whichever is easier for you.

@tgrospic

Copy link
Copy Markdown
Member

@tgrospic tgrospic closed this Oct 29, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants