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 ownerdraft=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.
contentLanguageCodeis kept asenwhen the hub language changes. - Completed translations are cached in
GUIDE_MEDIA(R2) by guide id + languages + content fingerprint. Partial runs are also cached (await R2put) and resumed on the next request, so Owner↔Guest and revisits keep filling the map until complete. Worker logs taggedguide-i18nshow progress (cached/uniquecounts). - 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.
- Search the JSON for the topic title (e.g.
"Scooter","Heating"). - Edit text inside
"blocks"— look for"content","steps", or"items". - Run
npm run devand check House Guide in the browser. - Commit and push; Cloudflare Pages redeploys.
A short cheat sheet lives next to the file: src/content/houseguide/README.md.
Validate before push
npm test -- tests/guideCatalog.test.js tests/guideMedia.test.jsOr the full suite: npm run check.
Block types
| type | use for |
|---|---|
text | Paragraph (content, optional heading) |
steps | Numbered list (steps array) |
tip / warning / note | Callout boxes |
keyValues | Label/value pairs |
heroImage | One photo via mediaId (optional caption) |
gallery | Several 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 |
place | Local pub/walk entries |
protected | Wi‑Fi, contacts, lockbox — resolved at runtime |
wifiQr | Wi‑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:
"hot-water-machine-controls": {
"file": "hot-water-machine-controls.jpg",
"alt": "Button layout on the hot water machine"
}Reference from a topic:
{ "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 referencenpm run guide:build-catalog— regenerates JSON fromscripts/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.