Skip to content

House Guide content ​

Live translation (hub UI language) ​

Published guide catalogs can be live-translated when the hub UI language differs from the content language (the language guides were written in).

  • API: GET /api/house-guide/catalog?lang={ui}&source={content} (skipped for owner draft=1)
  • Engine: Cloudflare Workers AI @cf/meta/m2m100-1.2b
  • Content language is English (guides are authored in English). The hub never live-translates “back” into English. contentLanguageCode is kept as en when the hub language changes.
  • Completed translations are cached in GUIDE_MEDIA (R2) by guide id + languages + content fingerprint. Partial runs are also cached (await R2 put) and resumed on the next request, so Owner↔Guest and revisits keep filling the map until complete. Worker logs tagged guide-i18n show progress (cached / unique counts).
  • Cost of live translation is visible on the Grafana AI usage dashboard (Workers AI neurons → estimated billable USD).
  • Owners editing drafts always see the source (untranslated) catalog.

Edit the guide (normal workflow) ​

File: src/content/houseguide/guide-catalog.json

This is the only file you need for copy changes. The app reads it directly — no Python, no rebuild.

  1. Search the JSON for the topic title (e.g. "Scooter", "Heating").
  2. Edit text inside "blocks" — look for "content", "steps", or "items".
  3. Run npm run dev and check House Guide in the browser.
  4. Commit and push; Cloudflare Pages redeploys.

A short cheat sheet lives next to the file: src/content/houseguide/README.md.

Validate before push ​

bash
npm test -- tests/guideCatalog.test.js tests/guideMedia.test.js

Or the full suite: npm run check.

Block types ​

typeuse for
textParagraph (content, optional heading)
stepsNumbered list (steps array)
tip / warning / noteCallout boxes
keyValuesLabel/value pairs
heroImageOne photo via mediaId (optional caption)
gallerySeveral photos via mediaIds (optional heading): side by side where there is room, one per row on phones. Added in the Guide Editor as Photo gallery
placeLocal pub/walk entries
protectedWi‑Fi, contacts, lockbox — resolved at runtime
wifiQrWi‑Fi QR code drawn from the saved Wi‑Fi name and password (optional heading, caption). Shows when the details will appear until the visitor may see them

Topic titles, subtitles and summaries are shown exactly as stored: cards, search and Lottie all read them, so there is no "coming soon" text to patch at draw time. Hub D1 migration 0018 turned the old seeded Wi‑Fi "QR Code" placeholder page into a real QR page (#1344).

Full typedefs: src/types/guideContent.js.

Images ​

Photos go in src/content/houseguide/media/. Register each image in the "media" map at the top of guide-catalog.json:

json
"hot-water-machine-controls": {
  "file": "hot-water-machine-controls.jpg",
  "alt": "Button layout on the hot water machine"
}

Reference from a topic:

json
{ "type": "heroImage", "mediaId": "hot-water-machine-controls", "caption": "Button layout" }

guideMediaValidate.js (run via Vitest) checks that every mediaId has a file and alt text.

Private values (not in git) ​

Copy private-content.example.json → private-content.local.json on trusted devices. Protected blocks in the catalog use dot-path keys such as wifi.password and contacts.mark.phone.

For production tablets, plan to inject these via Cloudflare Access–protected configuration rather than committing real values.

Legacy PDF / Python tooling (optional) ​

You can ignore this unless you are doing a bulk re-import from a TrustedHousesitters PDF.

  • PDF (gitignored): src/content/houseguide/source/house-guide.pdf
  • npm run guide:extract — dumps raw PDF text for reference
  • npm run guide:build-catalog — regenerates JSON from scripts/build_house_guide_catalog.py

Do not run guide:build-catalog after hand-editing JSON — it will overwrite your changes. The Python script is maintained for historical bulk builds; day-to-day edits belong in guide-catalog.json.