Make website and guides available in other languages #172

LibreMesh is used by community mesh networks in many places where English isn't the first language, and right now the docs and guides are English-only. The site is VitePress, which has built-in i18n, so adding languages is mostly a content effort, not an engineering one.

Goal

Ship the site in Spanish (/es/) and Brazilian Portuguese (/pt-BR/) as the first two non-English locales, with a language switcher in the nav and a friendly first-visit prompt for visitors whose browser is in one of those languages. Then grow from there.

Why this approach

• VitePress locales does the heavy lifting. It generates the language menu in the nav automatically, sets <html lang="...">, and routes /es/... and /pt-BR/... to the right directory. No build pipeline changes, no new dependencies.
• Translations live in the same repo, as plain markdown under docs/es/ and docs/pt-BR/, mirroring the English structure. The existing editLink config already points contributors to the right file on GitHub.
• Auto-generated pages stay in English (the package and profile pages are built from git submodules by prepare_data.js — hundreds of them, not realistic to translate by hand). If a translated page links to one of them, we link out to the English version with a small "in English" hint, rather than mixing languages on the same page. Cleaner, easier to maintain.
• No Crowdin / Weblate / CI translation infra for v1. Plain PRs, native speakers reviewing. If we ever want machine translation, a small LLM-based script can be bolted on later (see "Future" below) without changing the directory layout.

Concrete changes

1. docs/.vitepress/config.mts — add the two locales:

locales: {
  root:  { label: 'English',            lang: 'en' },
  es:    { label: 'Español',            lang: 'es',    link: '/es/' },
  'pt-BR': { label: 'Português (BR)',   lang: 'pt-BR', link: '/pt-BR/' },
},

That alone gives us the language menu in the nav.

2. Mirror the English content tree under docs/es/ and docs/pt-BR/. Start with the highest-traffic pages: what-is-libremesh, getting-started, guide/connecting, guide/packages-selection, guide/upgrade, build/, reference/configuration, development/. Everything else links out to English.

3. Localized nav/sidebar labels. Move nav() and sidebarGuide() to a per-locale config (or use the link + themeConfig override pattern) so the nav items read "Guía", "Referencia", etc. in Spanish and "Guia", "Referência" in pt-BR. If a label isn't translated yet, fall back to English — better than a half-translated menu.

4. First-visit browser-language prompt. Add a small theme/Layout.vue (≤30 lines) that, on first visit with no stored preference, checks navigator.language against ['es', 'pt-BR'] and shows a dismissible banner: "This site is also available in Español / Português (BR) — switch?" User choice is stored in localStorage so we don't ask again. No jarring redirect, no content flash.

5. Add docs/TRANSLATING.md with a tiny glossary (keep "Batman-adv", "mesh node", "LiMe" untranslated), tone notes, and the link-out convention.

What's intentionally out of scope for v1

• Translating the auto-generated package/profile pages.
• Server-side language detection (we're on GitHub Pages; would need a CDN in front).
• A translation management platform.

Future

• An LLM-powered translation script (suggested, not committed): a small scripts/translate.mjs that reads docs/**/*.md, sends untranslated pages to a translation API, writes the result to docs/<lang>/ as a draft PR for a native speaker to review. The directory layout we pick today is compatible with that — no rework needed.

Acceptance criteria for the first PR

• es and pt-BR added to locales in config.mts.
• Language switcher visible in the nav, routes to /es/ and /pt-BR/.
• At minimum, what-is-libremesh, getting-started, and guide/connecting translated in both languages.
• First-visit banner appears for es-* / pt-BR browser locales and remembers the choice.
• Pages not yet translated link out to their English version with a visible hint.
• pnpm build still passes.