Repository navigation
feat(doc): serve the doc site in English and German - #48
Merged
Merged
Conversation
added 11 commits
October 4, 2026 19:50
Replaces the 157 include:markdown-it lines with a md() Pug helper. It prints the same English html (the 28 compiled pages are byte-identical before and after) and wraps it for rv-i18n-html only when a translated sibling file exists.
build-locales.js collects UI strings (src/locales/<lang>/*.yml), demo README.<lang>.md titles and descriptions, and translated markdown pages that md() renders into one JSON tree per language. A Vite plugin emits them as locales/<lang>.json and serves them in the dev server. The README metadata readers moved to readme-metadata.js so both builds parse a README alike.
main.ts registers a rest locales service (locales/<lang>.json, English source, detect query/storage/navigator, persisted) with an i18n-switcher in the navbar. The sidebar titles carry rv-i18n-text keys, the bundled i18n-static example messages still load for de and en, and Prism re-highlights after a switch.
The UI strings are English markup now, German comes from src/locales/de/ui.yml. The gallery cards use rv-i18n-text keyed by demo id with the manifest text as source; the viewer builds its title, description, status and meta line through uiText() and refreshes on language change. The spec expects English and covers German and the English fallback.
The 34 German READMEs move to README.de.md (history follows the rename) and get an English README.md, which is the canonical text of the doc registry. The German ones feed the de catalog.
The ten Tailwind demos had no README, so their cards showed an empty description. Each README is derived from the demo source.
The English README.md is the canonical text of the registry and the fallback of every translation, so a demo without one is an error. watch.js now also reacts to README edits outside src/.
Reports translations without an English sibling, translated pages no page renders, orphan catalog keys, placeholders that differ from the English text, demos without an English description and invalid YAML or JSON.
Matches build-demos.js and the other scripts of infra/doc.
After the demos, a language phase loads demos.html and demo.html in English and with ?lang=de. It fails on console errors, on a card or viewer that does not show the catalog text, and on an untranslated demo that does not fall back to its English description.
check:locales runs with the workspace check and before the docs deploy.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
English is the markup of the doc site; German (and any further language) comes from a catalog that
@ribajs/i18nloads at runtime once the language is active (?lang=de, the navbar switcher, browser language, remembered inlocalStorage). A text without a translation stays English. Builds on #47.md()Pug helper replaces the 157include:markdown-itlines. The English html is byte-identical to before (28 compiled pages compared before/after the codemod); a page is wrapped inrv-i18n-htmlonly when a<page>.<lang>.mdsibling exists.build-locales.js+ Vite plugin): UI strings fromsrc/locales/<lang>/*.yml, demo titles/descriptions fromdemos/<id>/README.<lang>.md, translated markdown pages. Emitted aslocales/<lang>.json(build and dev server), only for languages with content.main.tsregisters a rest locales service (English source, detect query/storage/navigator, persisted), ani18n-switcherin the navbar, translated sidebar titles, Prism re-highlighting after a switch.src/locales/de/ui.yml; cards and viewer fall back to the English manifest text.README.de.md(history follows) and got an EnglishREADME.md; the 10tw-*demos got a README.build:demosnow fails for a demo without an English description.yarn workspace @ribajs/doc check:locales(part ofcheck, also in the deploy workflow): translation without English sibling, translated page nobody renders, orphan keys, differing{{ placeholders }}, missing English description, invalid YAML/JSON.smoke:demoshas a language phase (?lang=degallery and viewer, English fallback for an untranslated demo).Verification
yarn test: 962 passed (941 before)build:demos45/45, doc build ok,smoke:demos45 ok + language phase 4/4,check:localesok,tscforinfra/doc?lang=de, navigator languagede-DE, switch via button, PJAX navigation and reload keep German; a temporary translated page with example tabs swapped en → de → en with unchanged structure and Prism tokens (spike, not committed)e2e/only drives the demos (router-*,hook-order), none of the changed selectors;yarn test:e2edoes not run locally, so CI is its first runNot run: ESLint (the repo config does not load on
maineither),yarn build:libs. No guide or reference page is translated yet; the mechanism is ready (<page>.de.mdnext to<page>.md).