@voltro/cli 0.1.0

package/templates/apps/frontend-docs/src/lib/locale.ts

@@ -0,0 +1,56 @@
+// The single source of truth for this app's locales + the URL-prefix
+// helpers. `app.config.ts` lists the same codes for the build pipeline;
+// the [locale] mirror pages + the layout's <I18nProvider> read THIS file.
+//
+// Keep SUPPORTED_LOCALES / DEFAULT_LOCALE in sync with `locales` /
+// `defaultLocale` in app.config.ts.
+
+import { useLocation } from '@voltro/web'
+import en from '../locales/en'
+import de from '../locales/de'
+
+export const SUPPORTED_LOCALES = ['en', 'de'] as const
+export const DEFAULT_LOCALE = 'en'
+
+export type Locale = (typeof SUPPORTED_LOCALES)[number]
+
+// The catalogs, keyed by code. The layout picks one to feed the inner
+// <I18nProvider>; `meta` (build-time, per locale) reads one via getCatalog.
+export const CATALOGS = { en, de } as const
+
+// Every catalog mirrors `en`'s keys (defineLocale enforces it), so a
+// plain string-record over en's keys is the common type both satisfy —
+// what `meta` reads at build time (`c['meta.home.title']` → string), and
+// what the docs table's title/body keys are typed against.
+export type Messages = Record<keyof typeof en, string>
+
+const isSupported = (v: string): v is Locale =>
+  (SUPPORTED_LOCALES as ReadonlyArray<string>).includes(v)
+
+export const getCatalog = (locale: string): Messages =>
+  isSupported(locale) ? CATALOGS[locale] : CATALOGS[DEFAULT_LOCALE]
+
+// `/de/docs/x` → 'de'; `/docs/x` → 'en' (default lives at the bare path).
+export const localeFromPathname = (pathname: string): Locale => {
+  const match = /^\/([a-z]{2})(?:\/|$)/.exec(pathname)
+  return match && isSupported(match[1]!) ? (match[1] as Locale) : DEFAULT_LOCALE
+}
+
+// Reactive: useLocation re-renders on client-side nav, so the layout's
+// provider swaps catalogs when you move between /docs/x and /de/docs/x
+// without a full reload.
+export const useUrlLocale = (): Locale => localeFromPathname(useLocation())
+
+// '/docs/x' + 'de' → '/de/docs/x'; the default locale stays bare.
+export const withLocalePrefix = (path: string, locale: string): string => {
+  if (locale === DEFAULT_LOCALE) return path
+  const p = path.startsWith('/') ? path : `/${path}`
+  return p === '/' ? `/${locale}` : `/${locale}${p}`
+}
+
+// '/de/docs/x' → '/docs/x'; '/docs/x' → '/docs/x'. The inverse of the
+// above, used to keep the active path when switching language.
+export const stripLocalePrefix = (pathname: string): string => {
+  const match = /^\/([a-z]{2})(\/.*|$)/.exec(pathname)
+  return match && isSupported(match[1]!) ? match[2] || '/' : pathname
+}

package/templates/apps/frontend-docs/src/locales/de.ts

@@ -0,0 +1,24 @@
+// German catalog. MUST mirror en.ts key-for-key — `defineLocale<typeof en>()`
+// returns a curried function that fails `tsc --noEmit` on a missing or extra
+// key, so translations can never silently drift out of sync.
+import { defineLocale } from '@voltro/i18n'
+import en from './en'
+
+export default defineLocale<typeof en>()({
+  'nav.home':     'Start',
+  'nav.language': 'Sprache',
+
+  'home.title': '{project} Dokumentation',
+
+  'docs.getting-started.title': 'Erste Schritte',
+  'docs.getting-started.body':  'Willkommen in der {{capProjectName}}-Dokumentation.',
+  'docs.first-page.title':      'Deine erste Seite',
+  'docs.first-page.body':       'Lege eine `*.tsx`-Datei in src/pages/ ab.',
+
+  'docs.notFound.title': 'Nicht gefunden',
+  'docs.notFound.body':  'Kein Dokument unter <code>{slug}</code>.',
+
+  'meta.home.title':       'Dokumentation',
+  'meta.home.description': 'Eine zweisprachige Dokumentationsseite mit Voltro — Englisch am bloßen Pfad, Deutsch unter /de.',
+  'meta.docs.description': 'Referenzdokumentation, pro Sprache als statisches HTML vorgerendert.',
+})

package/templates/apps/frontend-docs/src/locales/en.ts

@@ -0,0 +1,28 @@
+// Base catalog — the source of truth. Every other locale (de.ts) mirrors
+// these keys EXACTLY; `defineLocale<typeof en>()` enforces that at `tsc`.
+//
+// The doc pages are keyed by SLUG (stable across locales — the URL structure
+// is the same, only the /de prefix differs); the per-locale title + body come
+// from these `docs.*` entries. Keep ICU placeholders (`{project}`, `{slug}`)
+// + rich-text tags (`<code>`) identical across locales.
+import { defineCatalog } from '@voltro/i18n'
+
+export default defineCatalog({
+  'nav.home':     'Home',
+  'nav.language': 'Language',
+
+  // `{project}` is the scaffold-substituted app name, passed as a <T> value.
+  'home.title': '{project} docs',
+
+  'docs.getting-started.title': 'Getting started',
+  'docs.getting-started.body':  'Welcome to the {{capProjectName}} docs.',
+  'docs.first-page.title':      'Your first page',
+  'docs.first-page.body':       'Drop a `*.tsx` file into src/pages/.',
+
+  'docs.notFound.title': 'Not found',
+  'docs.notFound.body':  'No doc at <code>{slug}</code>.',
+
+  'meta.home.title':       'Documentation',
+  'meta.home.description': 'A bilingual documentation site built with Voltro — English at the bare path, German under /de.',
+  'meta.docs.description': 'Reference documentation, pre-rendered per locale as static HTML.',
+} as const)

package/templates/apps/frontend-docs/src/pages/[locale]/docs/[...slug].tsx

@@ -0,0 +1,18 @@
+// Locale mirror of the catch-all docs route → renders `/de/docs/<slug>`.
+// Re-exports the bare `[...slug]` page (the component + its per-locale meta
+// read locale + slug from the URL / params). This is a DYNAMIC route mirrored
+// under a DYNAMIC locale segment, so `getStaticPaths` must emit the
+// CROSS-PRODUCT of every non-default locale × every doc slug — otherwise the
+// German docs URLs are never enumerated for pre-render.
+import { SUPPORTED_LOCALES, DEFAULT_LOCALE } from '../../../lib/locale'
+import { DOCS } from '../../docs/[...slug]'
+
+export { default } from '../../docs/[...slug]'
+export { renderMode, interactive, meta } from '../../docs/[...slug]'
+
+export const getStaticPaths = async (): Promise<
+  Array<{ params: { locale: string; slug: string } }>
+> =>
+  SUPPORTED_LOCALES
+    .filter((l) => l !== DEFAULT_LOCALE)
+    .flatMap((locale) => DOCS.map((d) => ({ params: { locale, slug: d.slug } })))

package/templates/apps/frontend-docs/src/pages/[locale]/index.tsx

@@ -0,0 +1,13 @@
+// Locale mirror of `/` → renders `/de`. Re-exports the bare docs landing
+// (the component reads its locale from the URL via the layout's provider);
+// `getStaticPaths` tells `voltro build` which locale-prefixed paths to emit.
+// The default locale is NOT listed here — it lives at the bare `/`.
+import { SUPPORTED_LOCALES, DEFAULT_LOCALE } from '../../lib/locale'
+
+export { default } from '../index'
+export { renderMode, interactive, meta } from '../index'
+
+export const getStaticPaths = async (): Promise<Array<{ params: { locale: string } }>> =>
+  SUPPORTED_LOCALES
+    .filter((l) => l !== DEFAULT_LOCALE)
+    .map((locale) => ({ params: { locale } }))

package/templates/apps/frontend-docs/src/pages/[locale]/mirrors.test.tsx

@@ -0,0 +1,67 @@
+// @vitest-environment jsdom
+//
+// The [locale] mirror pages re-export the bare pages and add getStaticPaths,
+// which tells `voltro build` which locale-prefixed paths to emit. The default
+// locale (en) is NOT listed — it lives at the bare path. The docs [...slug]
+// mirror is the interesting case: a DYNAMIC route under a DYNAMIC locale
+// segment, so its getStaticPaths must emit the CROSS-PRODUCT of every
+// non-default locale × every doc slug.
+
+import { describe, expect, test, vi } from 'vitest'
+
+// The mirrors transitively import the base pages, which import @voltro/i18n
+// and @voltro/web. Stub both so importing the modules doesn't require the
+// real runtimes.
+vi.mock('@voltro/web', () => ({
+  useLocation: () => '/',
+  useParams: () => ({ slug: '' }),
+}))
+
+vi.mock('@voltro/i18n', () => ({
+  // The locale catalogs call these at module top-level; identity mirrors the
+  // real (compile-time-only) implementations so importing them doesn't throw.
+  defineCatalog: <T,>(c: T): T => c,
+  defineLocale:
+    () =>
+    <T,>(c: T): T =>
+      c,
+  useLocale: () => 'en',
+  useTFn: () => (id: string) => id,
+  T: ({ id }: { id: string }) => id,
+}))
+
+const indexMirror = await import('./index')
+const slugMirror = await import('./docs/[...slug]')
+
+describe('home mirror — getStaticPaths', () => {
+  test('emits only non-default locales (just /de)', async () => {
+    const paths = await indexMirror.getStaticPaths()
+    expect(paths).toEqual([{ params: { locale: 'de' } }])
+  })
+
+  test('re-exports the base page component + its meta function', () => {
+    expect(typeof indexMirror.default).toBe('function')
+    expect(indexMirror.meta({ locale: 'de' }).title).toBe('Dokumentation')
+    expect(indexMirror.renderMode).toBe('static')
+    expect(indexMirror.interactive).toBe('none')
+  })
+})
+
+describe('docs [...slug] mirror — getStaticPaths (locale × slug cross-product)', () => {
+  test('emits every non-default locale paired with every doc slug', async () => {
+    const paths = await slugMirror.getStaticPaths()
+    expect(paths).toEqual([
+      { params: { locale: 'de', slug: 'intro/getting-started' } },
+      { params: { locale: 'de', slug: 'guides/first-page' } },
+    ])
+  })
+
+  test('re-exports the base page component + its per-locale meta function', () => {
+    expect(typeof slugMirror.default).toBe('function')
+    expect(
+      slugMirror.meta({ locale: 'de', params: { slug: 'guides/first-page' } }).title,
+    ).toBe('Deine erste Seite')
+    expect(slugMirror.renderMode).toBe('static')
+    expect(slugMirror.interactive).toBe('none')
+  })
+})

package/templates/apps/frontend-docs/src/pages/docs/[...slug].test.tsx

@@ -0,0 +1,115 @@
+// @vitest-environment jsdom
+//
+// `/docs/[...slug]` catch-all — its `getStaticPaths` export (enumerates the
+// pre-rendered doc slugs) and the localized page render for a matched vs.
+// unknown slug. The page reads the captured slug via `useParams` (mocked to
+// drive the slug) and its per-locale prose via @voltro/i18n (mocked to resolve
+// against the real catalogs for a controllable "current locale").
+
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+import { act, createElement, type ReactNode } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import en from '../../locales/en'
+import de from '../../locales/de'
+
+const params = vi.fn<() => Record<string, string>>()
+vi.mock('@voltro/web', () => ({ useParams: () => params() }))
+
+const catalogs: Record<string, Record<string, string>> = { en, de }
+let currentLocale = 'en'
+
+const fill = (msg: string, values?: Record<string, unknown>): string =>
+  values ? msg.replace(/\{(\w+)\}/g, (_, k: string) => String(values[k] ?? `{${k}}`)) : msg
+
+vi.mock('@voltro/i18n', () => ({
+  // The locale catalogs call these at module top-level; identity mirrors the
+  // real (compile-time-only) implementations so importing them doesn't throw.
+  defineCatalog: <T,>(c: T): T => c,
+  defineLocale:
+    () =>
+    <T,>(c: T): T =>
+      c,
+  useTFn:
+    () =>
+    (id: string, values?: Record<string, unknown>) =>
+      fill(catalogs[currentLocale]?.[id] ?? id, values),
+  T: ({ id, values }: { id: string; values?: Record<string, unknown> }) =>
+    fill(catalogs[currentLocale]?.[id] ?? id, values),
+}))
+
+const { default: DocPage, getStaticPaths, meta, renderMode, interactive } = await import('./[...slug]')
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+let container: HTMLDivElement
+let root: Root
+
+const render = (node: ReactNode): void => {
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  act(() => {
+    root = createRoot(container)
+    root.render(node)
+  })
+}
+
+beforeEach(() => params.mockReset())
+
+afterEach(() => {
+  currentLocale = 'en'
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+})
+
+describe('docs [...slug] — config + getStaticPaths', () => {
+  test('is a static page with no client JS', () => {
+    expect(renderMode).toBe('static')
+    expect(interactive).toBe('none')
+  })
+
+  test('enumerates every doc slug as a single `/`-joined string', async () => {
+    const paths = await getStaticPaths()
+    expect(paths.map((p) => p.params.slug)).toEqual([
+      'intro/getting-started',
+      'guides/first-page',
+    ])
+  })
+})
+
+describe('docs [...slug] — localized meta', () => {
+  test('reads the per-doc title from the catalog, per locale', () => {
+    expect(meta({ locale: 'en', params: { slug: 'guides/first-page' } }).title).toBe('Your first page')
+    expect(meta({ locale: 'de', params: { slug: 'guides/first-page' } }).title).toBe('Deine erste Seite')
+  })
+
+  test('falls back to the not-found title for an unknown slug', () => {
+    expect(meta({ locale: 'en', params: { slug: 'does/not-exist' } }).title).toBe('Not found')
+  })
+})
+
+describe('docs [...slug] — localized render', () => {
+  test('renders the matched doc title + body (English) for a known slug', () => {
+    currentLocale = 'en'
+    params.mockReturnValue({ slug: 'guides/first-page' })
+    render(createElement(DocPage))
+    expect(container.querySelector('h1')?.textContent).toBe('Your first page')
+    expect(container.textContent).toContain('Drop a')
+  })
+
+  test('renders the matched doc title + body (German) for a known slug', () => {
+    currentLocale = 'de'
+    params.mockReturnValue({ slug: 'guides/first-page' })
+    render(createElement(DocPage))
+    expect(container.querySelector('h1')?.textContent).toBe('Deine erste Seite')
+    expect(container.textContent).toContain('Lege eine')
+  })
+
+  test('renders the localized not-found fallback for an unknown slug', () => {
+    currentLocale = 'en'
+    params.mockReturnValue({ slug: 'does/not-exist' })
+    render(createElement(DocPage))
+    expect(container.querySelector('h1')?.textContent).toBe('Not found')
+    expect(container.textContent).toContain('does/not-exist')
+  })
+})

package/templates/apps/frontend-docs/src/pages/docs/[...slug].tsx

@@ -0,0 +1,82 @@
+// Catch-all docs router. Renders the localized content for any
+// `/docs/<path>` URL (and its `/de/docs/<path>` mirror). `getStaticPaths`
+// enumerates the doc tree at build time so every page is pre-rendered.
+//
+// Bilingual (Strategy B): the doc SLUG is stable across locales — only the
+// /de URL prefix differs — so each entry carries a `titleKey` / `bodyKey`
+// into the message catalog rather than literal, one-language strings. The
+// [locale] mirror (src/pages/[locale]/docs/[...slug].tsx) re-exports this
+// page and emits the cross-product of non-default locales × these slugs.
+
+import type { ReactNode } from 'react'
+import type { PageMeta } from '@voltro/web'
+import { useParams } from '@voltro/web'
+import { T, useTFn } from '@voltro/i18n'
+import { getCatalog, type Messages } from '../../lib/locale'
+
+export const renderMode = 'static' as const
+export const interactive = 'none' as const
+
+interface DocEntry {
+  readonly slug: string
+  readonly titleKey: keyof Messages
+  readonly bodyKey: keyof Messages
+}
+
+// The doc tree — slugs stay identical across locales; the per-locale prose
+// lives in the catalogs. Replace with a loader over a markdown folder / CMS
+// / database query; the shape stays the same.
+export const DOCS: ReadonlyArray<DocEntry> = [
+  { slug: 'intro/getting-started', titleKey: 'docs.getting-started.title', bodyKey: 'docs.getting-started.body' },
+  { slug: 'guides/first-page',     titleKey: 'docs.first-page.title',      bodyKey: 'docs.first-page.body' },
+]
+
+// getStaticPaths returns `{ params: { slug: '<path>' } }` entries — the
+// framework substitutes each into `/docs/[...slug]` to enumerate the URLs
+// to pre-render. The captured slug is the raw `/`-joined path (NOT a string
+// array) so a single deep slug like 'intro/getting-started' renders one file.
+export const getStaticPaths = async (): Promise<Array<{ params: { slug: string } }>> =>
+  DOCS.map((d) => ({ params: { slug: d.slug } }))
+
+// Per-locale, per-doc <title>: reads the active locale + the captured slug
+// (both threaded in at SSG time) so each variant's head is localised.
+export const meta = ({
+  locale,
+  params,
+}: {
+  locale: string
+  params: Readonly<Record<string, string>>
+}): PageMeta => {
+  const c = getCatalog(locale)
+  const doc = DOCS.find((d) => d.slug === params.slug)
+  return {
+    title: doc ? c[doc.titleKey] : c['docs.notFound.title'],
+    description: c['meta.docs.description'],
+  }
+}
+
+const code = (chunks: ReactNode): ReactNode => <code>{chunks}</code>
+
+export default function DocPage(): ReactNode {
+  const { slug } = useParams<{ slug: string }>()
+  const t = useTFn()
+  const doc = DOCS.find((d) => d.slug === slug)
+  if (!doc) {
+    return (
+      <article>
+        <h1>
+          <T id="docs.notFound.title" />
+        </h1>
+        <p>
+          <T id="docs.notFound.body" values={{ slug, code }} />
+        </p>
+      </article>
+    )
+  }
+  return (
+    <article>
+      <h1>{t(doc.titleKey)}</h1>
+      <p>{t(doc.bodyKey)}</p>
+    </article>
+  )
+}

package/templates/apps/frontend-docs/src/pages/index.test.tsx

@@ -0,0 +1,90 @@
+// @vitest-environment jsdom
+//
+// `/` docs landing — a bilingual static page (Strategy B). Its links are
+// locale-prefixed off the active locale via `withLocalePrefix`, so /de's
+// landing points at the /de docs. We assert the render-mode config, the
+// localized meta, and that the links resolve to the right locale's URLs.
+// The heading carries a `{{capProjectName}}` scaffold placeholder threaded in
+// as a <T> value, so we assert the localized suffix, not the substituted name.
+
+import { afterEach, describe, expect, test, vi } from 'vitest'
+import { act, createElement, type ReactNode } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import en from '../locales/en'
+import de from '../locales/de'
+
+const catalogs: Record<string, Record<string, string>> = { en, de }
+let currentLocale = 'en'
+
+const fill = (msg: string, values?: Record<string, unknown>): string =>
+  values ? msg.replace(/\{(\w+)\}/g, (_, k: string) => String(values[k] ?? `{${k}}`)) : msg
+
+vi.mock('@voltro/i18n', () => ({
+  // The locale catalogs call these at module top-level; identity mirrors the
+  // real (compile-time-only) implementations so importing them doesn't throw.
+  defineCatalog: <T,>(c: T): T => c,
+  defineLocale:
+    () =>
+    <T,>(c: T): T =>
+      c,
+  useLocale: () => currentLocale,
+  T: ({ id, values }: { id: string; values?: Record<string, unknown> }) =>
+    fill(catalogs[currentLocale]?.[id] ?? id, values),
+}))
+
+const { default: Index, meta, renderMode, interactive } = await import('./index')
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+let container: HTMLDivElement
+let root: Root
+
+const render = (node: ReactNode): void => {
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  act(() => {
+    root = createRoot(container)
+    root.render(node)
+  })
+}
+
+const hrefs = (): Array<string | null> =>
+  Array.from(container.querySelectorAll('a')).map((a) => a.getAttribute('href'))
+
+afterEach(() => {
+  currentLocale = 'en'
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+})
+
+describe('index — config + localized meta', () => {
+  test('is a static page with no client JS', () => {
+    expect(renderMode).toBe('static')
+    expect(interactive).toBe('none')
+  })
+
+  test('meta() is localized per locale', () => {
+    expect(meta({ locale: 'en' }).title).toBe('Documentation')
+    expect(meta({ locale: 'de' }).title).toBe('Dokumentation')
+    expect(meta({ locale: 'zz' }).title).toBe('Documentation')
+  })
+})
+
+describe('index — localized render', () => {
+  test('links to both doc pages with bare (en) URLs and English titles', () => {
+    currentLocale = 'en'
+    render(createElement(Index))
+    expect(hrefs()).toEqual(['/docs/intro/getting-started', '/docs/guides/first-page'])
+    expect(container.textContent).toContain('Getting started')
+    expect(container.textContent).toContain('Your first page')
+  })
+
+  test('prefixes the doc links with /de and shows German titles for locale de', () => {
+    currentLocale = 'de'
+    render(createElement(Index))
+    expect(hrefs()).toEqual(['/de/docs/intro/getting-started', '/de/docs/guides/first-page'])
+    expect(container.textContent).toContain('Erste Schritte')
+    expect(container.textContent).toContain('Deine erste Seite')
+  })
+})

package/templates/apps/frontend-docs/src/pages/index.tsx

@@ -0,0 +1,45 @@
+// Docs landing — link to the available doc pages. Keep this thin; the docs
+// themselves live under `src/pages/docs/[...slug].tsx`.
+//
+// Bilingual (Strategy B): mounted at `/` (default locale) and mirrored at
+// `/de` by src/pages/[locale]/index.tsx. The links are locale-prefixed off
+// the active locale so /de's landing points at the /de docs.
+
+import type { ReactNode } from 'react'
+import type { PageMeta } from '@voltro/web'
+import { T, useLocale } from '@voltro/i18n'
+import { getCatalog, withLocalePrefix } from '../lib/locale'
+
+export const renderMode = 'static' as const
+export const interactive = 'none' as const
+
+export const meta = ({ locale }: { locale: string }): PageMeta => {
+  const c = getCatalog(locale)
+  return {
+    title: c['meta.home.title'],
+    description: c['meta.home.description'],
+  }
+}
+
+export default function Index(): ReactNode {
+  const locale = useLocale()
+  return (
+    <main>
+      <h1>
+        <T id="home.title" values={{ project: '{{capProjectName}}' }} />
+      </h1>
+      <ul>
+        <li>
+          <a href={withLocalePrefix('/docs/intro/getting-started', locale)}>
+            <T id="docs.getting-started.title" />
+          </a>
+        </li>
+        <li>
+          <a href={withLocalePrefix('/docs/guides/first-page', locale)}>
+            <T id="docs.first-page.title" />
+          </a>
+        </li>
+      </ul>
+    </main>
+  )
+}

package/templates/apps/frontend-docs/src/pages/layout.test.tsx

@@ -0,0 +1,84 @@
+// @vitest-environment jsdom
+//
+// Root layout — renders the top nav whose Home link + language switcher are
+// locale-prefixed off the CURRENT url (useUrlLocale → useLocation). We mock
+// useLocation (@voltro/web) to drive the active locale, and mock @voltro/i18n so
+// <I18nProvider> is a pass-through and <T> resolves against the real catalogs.
+
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+import { act, createElement, type ReactNode } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import en from '../locales/en'
+import de from '../locales/de'
+
+const location = vi.fn<() => string>()
+vi.mock('@voltro/web', () => ({ useLocation: () => location() }))
+
+const catalogs: Record<string, Record<string, string>> = { en, de }
+const localeFor = (path: string): string => (/^\/de(?:\/|$)/.test(path) ? 'de' : 'en')
+
+vi.mock('@voltro/i18n', () => ({
+  // The locale catalogs call these at module top-level; identity mirrors the
+  // real (compile-time-only) implementations so importing them doesn't throw.
+  defineCatalog: <T,>(c: T): T => c,
+  defineLocale:
+    () =>
+    <T,>(c: T): T =>
+      c,
+  I18nProvider: ({ children }: { children?: ReactNode }) => children,
+  // The nav uses <T> for link labels; resolve against the catalog of the
+  // locale implied by the current path (matches what useUrlLocale computes).
+  T: ({ id }: { id: string }) => catalogs[localeFor(location())]?.[id] ?? id,
+}))
+
+const { default: Layout } = await import('./layout')
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+let container: HTMLDivElement
+let root: Root
+
+const render = (node: ReactNode): void => {
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  act(() => {
+    root = createRoot(container)
+    root.render(node)
+  })
+}
+
+const hrefs = (): Array<string | null> =>
+  Array.from(container.querySelectorAll('a')).map((a) => a.getAttribute('href'))
+
+beforeEach(() => location.mockReset())
+
+afterEach(() => {
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+})
+
+describe('docs layout — English (bare path)', () => {
+  test('renders a bare Home link, an English nav label and the DE switcher target', () => {
+    location.mockReturnValue('/docs/intro/getting-started')
+    render(createElement(Layout, { children: createElement('p', null, 'page') }))
+    const h = hrefs()
+    expect(h).toContain('/')
+    // the language switcher keeps you on the same doc, re-prefixed per locale
+    expect(h).toContain('/de/docs/intro/getting-started')
+    expect(container.textContent).toContain('Home')
+    expect(container.textContent).toContain('page')
+  })
+})
+
+describe('docs layout — German (/de prefix)', () => {
+  test('prefixes the home link with /de and renders German labels', () => {
+    location.mockReturnValue('/de/docs/intro/getting-started')
+    render(createElement(Layout, { children: null }))
+    const h = hrefs()
+    expect(h).toContain('/de')
+    // switching back to en strips the prefix
+    expect(h).toContain('/docs/intro/getting-started')
+    expect(container.textContent).toContain('Start')
+  })
+})