Skip to content

Latest commit

 

History

History
116 lines (86 loc) · 7.19 KB

plan.md

File metadata and controls

116 lines (86 loc) · 7.19 KB

Multilanguage / i18n Support Plan

Current State

  • 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) and content/zones/ (zone data pages) — all English, emitted by the C# generator
  • Names: ClientNames.cs is a static snapshot of the client's lang0000 (English) string dictionary
  • Zola config: default_language = "en", no languages list, no translations/ 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 Multilingual Model

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 at content/... if you prefer, but explicit per-lang dirs are cleaner)
  • Translation strings: translations/en.toml, translations/de.toml — accessed in templates via tr("key")
  • URLs: default language at /path/, others at /de/path/
  • Language switcher: language variable available in templates; switch_language filter for links

Phases

Phase 1 — UI chrome ✅ DONE

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: defines WIKI_I18N (per-language strings), WIKI_setLang(), WIKI_applyLang(); swaps textContent/innerHTML/placeholder/aria-label on tagged elements; updates WIKI_UI for JS consumers
  • templates/base.html — added data-i18n/data-i18n-ph/data-i18n-aria/data-i18n-html attributes to all 105 chrome elements; FR button in lang menu; early head script sets html[lang] before paint; lang toggle calls WIKI_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:

  1. Zola renders the English text (from config.extra.ui) into the HTML — works without JS, SEO-friendly
  2. static/i18n.js loads in <head>, reads localStorage('wiki-lang'), and on DOMContentLoaded swaps all tagged elements to the saved language
  3. The language toggle button calls WIKI_setLang('fr') which saves + re-applies immediately (no reload)
  4. Adding a new language = add a block to i18n.js STRINGS + add a button in the lang menu + add a translations/<lang>.toml for 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.

Phase 2 — Hand-written content ✅ DONE (Zola multilingual)

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

Phase 3 — Generated content ✅ DONE (runtime translation)

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 adds data-def="slug" attributes to all item/ore/zone links in the built HTML (35,962 attributes across 5,574 pages). Also sets data-page-def on <body> for the current page.
  • static/i18n.js (generated by tools/gen_i18n.py) — the applyLang() function swaps textContent on all [data-def] elements + updates the page <title> and <h1>.
  • The names section of each translations/<lang>.json maps 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:

  1. Create translations/<lang>.json with ui + names sections
  2. Run make build
  3. 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.

What Does NOT Need Per-Language 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_UI strings which come from tr())
  • 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)

Open Questions

  1. Which language(s) to target first? (German? French? The game's player base determines this.)
  2. 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?
  3. Search: per-language index or a combined one? Per-language is cleaner but means more files.
  4. URL structure: Zola's default is /de/path/ for non-default languages. Is that acceptable, or do we want a subdomain/custom setup?
  5. 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)?

Suggested First Target

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.