- UI chrome: 105 strings in
config.toml [extra.ui](nav labels, buttons, toasts, search) - Hand-written content: 38 pages under
content/features/,content/formats/,content/menu/,content/_index.md - Generated content: 5,537 pages under
content/content/(items, ores, recipes, deployables, shop) andcontent/zones/(zone data pages) — all English, emitted by the C# generator - Names:
ClientNames.csis a static snapshot of the client'slang0000(English) string dictionary - Zola config:
default_language = "en", nolanguageslist, notranslations/directory - Search index:
static/search_index.json— single-language, built from the same generated content - Zone maps (SVGs, PNGs, thumbnails): language-neutral, no change needed
Zola v0.23 supports multilingual sites natively:
default_language = "en",languages = ["en", "de"]- Content per language:
content/en/...,content/de/...(the default language can stay atcontent/...if you prefer, but explicit per-lang dirs are cleaner) - Translation strings:
translations/en.toml,translations/de.toml— accessed in templates viatr("key") - URLs: default language at
/path/, others at/de/path/ - Language switcher:
languagevariable available in templates;switch_languagefilter for links
Goal: the nav, topbar, search, toasts, and footer are translatable.
Implementation approach: Runtime JS language switching (no Zola tr(), no content restructuring, no URL changes). The English text is rendered by Zola as the default; JS swaps it at runtime based on localStorage('wiki-lang'). This avoids the need to restructure content into content/en/ + content/fr/ (that's Phase 2).
Files created/modified:
translations/en.toml— canonical English UI strings (105 keys)translations/fr.toml— French translations (105 keys)static/i18n.js— runtime switcher: definesWIKI_I18N(per-language strings),WIKI_setLang(),WIKI_applyLang(); swapstextContent/innerHTML/placeholder/aria-labelon tagged elements; updatesWIKI_UIfor JS consumerstemplates/base.html— addeddata-i18n/data-i18n-ph/data-i18n-aria/data-i18n-htmlattributes to all 105 chrome elements; FR button in lang menu; early head script setshtml[lang]before paint; lang toggle callsWIKI_setLang()tests/i18n.spec.js— 7 tests (14 with mobile): default EN, switch to FR, switch back, persistence, WIKI_UI update, aria-labels, menu state
How it works:
- Zola renders the English text (from
config.extra.ui) into the HTML — works without JS, SEO-friendly static/i18n.jsloads in<head>, readslocalStorage('wiki-lang'), and on DOMContentLoaded swaps all tagged elements to the saved language- The language toggle button calls
WIKI_setLang('fr')which saves + re-applies immediately (no reload) - Adding a new language = add a block to
i18n.js STRINGS+ add a button in the lang menu + add atranslations/<lang>.tomlfor reference
Test status: 108 passed / 0 failed (94 original + 14 new i18n)
Deliverable: UI chrome is fully translatable at runtime; French is the first additional language; content stays in English.
Status: Complete. Zola multilingual mode is configured (languages = {en, fr}).
English content stays in content/ (served at /), French in content/fr/ (served at
/fr/). The language switcher navigates to the translated page if one exists, otherwise
swaps chrome only.
Note: Content pages are NOT auto-translated. Each page must be manually written in
the target language under content/<lang>/. This is by design — the i18n system handles
chrome + game names automatically, but prose requires human translation. Adding a
translated page = create content/fr/<path>.md → make build.
What works now:
- UI chrome + game names: runtime translation (all languages, all pages)
- Content pages: per-language URLs when a translation exists (
/fr/features/faq/) - Language switcher: navigates to translated page if available, chrome-only otherwise
Status: Complete. Game names on generated pages (items, ores, zones) are translated at runtime using the same mechanism as the UI chrome.
Implementation:
tools/tag_defs.py— post-build script that addsdata-def="slug"attributes to all item/ore/zone links in the built HTML (35,962 attributes across 5,574 pages). Also setsdata-page-defon<body>for the current page.static/i18n.js(generated bytools/gen_i18n.py) — theapplyLang()function swapstextContenton all[data-def]elements + updates the page<title>and<h1>.- The
namessection of eachtranslations/<lang>.jsonmaps URL slugs to translated names. - Fallback: if a name is missing from the JSON, the English name is shown (no 404s, no blanks).
Build pipeline (in Makefile):
make build
→ make i18n (gen_i18n.py: translations/*.json → static/i18n.js)
→ Zola build (static site → public/)
→ tag_defs.py (adds data-def attributes to public/ HTML)
Adding a language:
- Create
translations/<lang>.jsonwithui+namessections - Run
make build - Done — the language appears in the topbar menu, chrome + names are translated
Test status: 108 passed / 0 failed
Deliverable: all generated page names (items, ores, zones) are translatable per language. No C# generator changes needed. No per-language content copies.
- Zone map SVGs (
static/zonemaps/*.svg) — language-neutral - Zone map PNGs (
static/zonemaps/<slug>/*.png) — language-neutral - World map thumbnail (
static/world-map-thumb.png) — language-neutral meta.tsv— language-neutral (zone slugs, dimensions)- CSS, JS (except the
WIKI_UIstrings which come fromtr()) recipes_data.json— the recipe structure is the same; item names in the JSON would need per-lang variants if the JSON is used for display (check if it is)
- Which language(s) to target first? (German? French? The game's player base determines this.)
- Where do the translated client strings come from? The game client has them, but do we have access to the string files, or do we need to extract them from the client?
- Search: per-language index or a combined one? Per-language is cleaner but means more files.
- URL structure: Zola's default is
/de/path/for non-default languages. Is that acceptable, or do we want a subdomain/custom setup? - Content parity: do we need 100% parity from day 1, or is it OK to have partial translations (some pages in English only until translated)?
Start with Phase 1 (UI chrome) — it's the quickest win, proves the Zola i18n plumbing works, and gives immediate value (nav labels in the target language even if the content is still English). Then pick the target language and do Phase 2. Phase 3 is the biggest lift and can wait until there's a confirmed translator + the client string data.