Builder
Tech
I am not an engineer. I wanted to build a site that I can keep up myself, so every choice below is a choice for simple and durable.
Claude Code
I built this site with Claude Code + VS Code. Based on my PRD, Claude created a spec and implementation plan. Each milestone ended with a review gate. Automated tests (unit tests, browser tests, accessibility and layout checks) run before anything is called done.
Astro
Astro builds the whole site ahead of time into plain pages. Visitors get fast, static HTML; there is no server and no database to look after. Pages that need a little interactivity (the map, the tabs, the search) add small scripts, and every page still reads without them.
TypeScript & JSON
TypeScript for the code, JSON files for the content: the experience, the talks, and the music engagements are data, not hand-written pages.
Markdown files
Essays are Markdown files. To publish a post, I drop a file in a folder. The Writer page, the search, the RSS feed, and the share card for the post all appear from that one file. Posts without image descriptions do not build, so accessibility cannot be forgotten.
The map
The map is drawn at build time from open geographic data as plain SVG. No map tiles, no map service, nothing loaded from another site.
Pagefind
Search is Pagefind: an index made at build time and searched in the browser, so no search service sees what visitors type.
Fonts
Fonts are self-hosted. No request leaves the site for fonts, YouTube thumbnails or analytics; a test checks that no page contacts a third party.
Light and dark
Light and dark follow the device. The sun and moon button only changes the look for the current visit.
Share cards
Share cards (the picture shown when a link is shared) are drawn at build time, with the translated name and tagline, and one per essay.
Internationalization
Internationalization (i18n) means building the site so that a language can be added without changing code. The site launched in English as its first language, but the global approach was built into its architecture from the start.
Routing and URLs
English pages have no language prefix (/writer/); other languages do (/pl/...). Automatic language detection is deliberately not used, users can choose their language. Every page links to its versions in the other languages for search engines.
Strings, plurals, dates
All text lives in JSON files. Nothing is hardcoded. Sentences are kept whole because concatenation breaks translations as soon as languages differ in syntax. Dates and numbers are formatted by the browser's own internationalization rules.
Right to left
The layout uses logical directions (start and end, not left and right), so a right-to-left language mirrors correctly. The map, which shows real geography, deliberately does not mirror.
Names
Proper names (companies, people, composers, orchestras, event names) are marked, so that no translation tool changes them. Descriptive names are translated, with the original in brackets after the translation.
Fonts and scripts
The fonts cover Latin letters, including Polish and German. A language in another script needs a fallback font, which is added together with the language.
Pseudolocalization
Test builds include two invented languages. One is English with accents, about a third longer and wrapped in brackets, to show where text would be cut off or overlap. The other is mirrored right to left. They never ship, they’re meant to catch errors and hardcoded text.
Localization
Localization (l10n) is the work of actually translating the site and adapting it to a language. The aim was that a translator, a translation tool or an AI agent can all do it from one file. Nothing is hardcoded.
Checklist
Before shipping a translation, the workflow checks for: string completeness, placeholders, diacritics, and potential hardcoded strings. When adding a new language, a font is added if the script needs one.
One file per language
Every string for a language lands in a single file. All user-facing copy sits outside the code.
Translation guidelines
Context is added in the translator notes. A separate guide explains what to translate and what to leave alone (names, product names, catalog numbers), the voice, and naming conventions. It is written to be read by people and by AI agents alike.
Do not translate
The essays stay in English. Names, composers, catalog numbers, and company names stay as they are. The Builder page you are reading is translated like every other page.