@voltro/cli 0.1.0

package/templates/apps/frontend-static-blog/src/lib/locale.test.ts

@@ -0,0 +1,72 @@
+// The URL-prefix i18n helpers — the load-bearing pure functions that drive the
+// [locale] mirror routing + the language switcher. `useUrlLocale` (the one hook
+// in this module) reads useLocation from @voltro/web; the rest are pure string
+// functions we can exercise directly.
+
+import { describe, expect, test } from 'vitest'
+import {
+  SUPPORTED_LOCALES,
+  DEFAULT_LOCALE,
+  getCatalog,
+  localeFromPathname,
+  withLocalePrefix,
+  stripLocalePrefix,
+} from './locale'
+
+describe('locale constants', () => {
+  test('supports en + de with en as the default', () => {
+    expect(SUPPORTED_LOCALES).toEqual(['en', 'de'])
+    expect(DEFAULT_LOCALE).toBe('en')
+  })
+})
+
+describe('getCatalog', () => {
+  test('returns the matching catalog for a supported locale', () => {
+    expect(getCatalog('de')['nav.language']).toBe('Sprache')
+    expect(getCatalog('en')['nav.language']).toBe('Language')
+  })
+
+  test('falls back to the default catalog for an unsupported locale', () => {
+    expect(getCatalog('zz')['nav.language']).toBe('Language')
+  })
+})
+
+describe('localeFromPathname', () => {
+  test('extracts a prefixed locale', () => {
+    expect(localeFromPathname('/de')).toBe('de')
+    expect(localeFromPathname('/de/about')).toBe('de')
+  })
+
+  test('defaults to en for the bare path or an unknown prefix', () => {
+    expect(localeFromPathname('/')).toBe('en')
+    expect(localeFromPathname('/about')).toBe('en')
+    expect(localeFromPathname('/fr/about')).toBe('en')
+  })
+})
+
+describe('withLocalePrefix', () => {
+  test('leaves default-locale paths bare', () => {
+    expect(withLocalePrefix('/about', 'en')).toBe('/about')
+    expect(withLocalePrefix('/', 'en')).toBe('/')
+  })
+
+  test('prefixes non-default locales, mapping / to /<locale>', () => {
+    expect(withLocalePrefix('/about', 'de')).toBe('/de/about')
+    expect(withLocalePrefix('/', 'de')).toBe('/de')
+  })
+})
+
+describe('stripLocalePrefix', () => {
+  test('removes a locale prefix, mapping /<locale> back to /', () => {
+    expect(stripLocalePrefix('/de/about')).toBe('/about')
+    expect(stripLocalePrefix('/de')).toBe('/')
+  })
+
+  test('leaves an unprefixed path unchanged', () => {
+    expect(stripLocalePrefix('/about')).toBe('/about')
+  })
+
+  test('round-trips with withLocalePrefix', () => {
+    expect(stripLocalePrefix(withLocalePrefix('/about', 'de'))).toBe('/about')
+  })
+})

package/templates/apps/frontend-static-blog/src/lib/locale.ts

@@ -0,0 +1,55 @@
+// 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).
+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/about` → 'de'; `/about` → '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 /about and /de/about
+// without a full reload.
+export const useUrlLocale = (): Locale => localeFromPathname(useLocation())
+
+// '/about' + 'de' → '/de/about'; the default locale stays bare ('/about').
+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/about' → '/about'; '/about' → '/about'. 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-static-blog/src/locales/de.ts

@@ -0,0 +1,19 @@
+// 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.language': 'Sprache',
+
+  'home.heading':   'Blog',
+  'home.postCount': '{count} Beiträge · zur Build-Zeit vorgerendert',
+
+  'post.readingTime':     '{minutes} Min.',
+  'post.readingTimeRead': '{minutes} Min. Lesezeit',
+  'post.backToList':      '← Alle Beiträge',
+
+  'meta.home.title':       '{{capProjectName}} — Blog',
+  'meta.home.description': 'Ein statischer, vorgerenderter Blog, gebaut mit Voltro.',
+})

package/templates/apps/frontend-static-blog/src/locales/en.ts

@@ -0,0 +1,26 @@
+// Base catalog — the source of truth. Every other locale (de.ts) mirrors
+// these keys EXACTLY; `defineLocale<typeof en>()` enforces that at `tsc`.
+//
+// CHROME ONLY: nav, headings, section labels + page meta live here. Post
+// titles / excerpts / bodies / dates are CONTENT (src/content/posts.ts) and
+// are NOT translated — they stay in the data source.
+//
+// Keep ICU placeholders (`{count}`, `{minutes}`) identical across locales —
+// react-intl validates them at render time. `{{capProjectName}}` is a scaffold
+// token (replaced by `voltro create-project`), only ever read from `meta`
+// (plain property access, never parsed as ICU) — leave it verbatim.
+import { defineCatalog } from '@voltro/i18n'
+
+export default defineCatalog({
+  'nav.language': 'Language',
+
+  'home.heading':   'Blog',
+  'home.postCount': '{count} posts · pre-rendered at build time',
+
+  'post.readingTime':     '{minutes} min',
+  'post.readingTimeRead': '{minutes} min read',
+  'post.backToList':      '← All posts',
+
+  'meta.home.title':       '{{capProjectName}} — Blog',
+  'meta.home.description': 'A static, pre-rendered blog built with Voltro.',
+} as const)

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

@@ -0,0 +1,20 @@
+// Locale mirror of `/blog/[slug]` → renders `/de/blog/<slug>`. Re-exports the
+// bare post page verbatim; only `getStaticPaths` differs.
+//
+// This is a DYNAMIC route under a DYNAMIC locale segment, so the paths to
+// pre-render are the CROSS-PRODUCT of every non-default locale × every post
+// slug (the bare page enumerates just the slugs; here each slug is emitted
+// once per non-default locale). `voltro build` produces one HTML file per
+// pair, e.g. /de/blog/hello-static.
+import { SUPPORTED_LOCALES, DEFAULT_LOCALE } from '../../../lib/locale'
+import { posts } from '../../../content/posts'
+
+export { default } from '../../blog/[slug]'
+export { renderMode, interactive, loader, meta } from '../../blog/[slug]'
+
+export const getStaticPaths = async (): Promise<
+  Array<{ params: { locale: string; slug: string } }>
+> =>
+  SUPPORTED_LOCALES
+    .filter((l) => l !== DEFAULT_LOCALE)
+    .flatMap((locale) => posts.map((post) => ({ params: { locale, slug: post.slug } })))

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

@@ -0,0 +1,13 @@
+// Locale mirror of `/` → renders `/de`. Re-exports the bare page verbatim
+// (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-static-blog/src/pages/[locale]/mirrors.test.tsx

@@ -0,0 +1,62 @@
+// @vitest-environment jsdom
+//
+// The [locale] mirror pages re-export the bare page 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 — so only /de is
+// produced. The dynamic post mirror emits the CROSS-PRODUCT of non-default
+// locales × post slugs (here: de × every post).
+
+import { describe, expect, test, vi } from 'vitest'
+import type { ComponentType } from 'react'
+import { posts } from '../../content/posts'
+
+// The mirrors transitively import the base pages, which import @voltro/web
+// (island / loader / notFound / useLocation via lib/locale) and @voltro/i18n.
+// Stub both so importing the modules doesn't require the real runtimes.
+vi.mock('@voltro/web', () => ({
+  useLoaderData: () => ({}),
+  notFound: (detail?: string) => {
+    throw new Error(detail)
+  },
+  island: (Component: ComponentType<unknown>) => Component,
+  useLocation: () => '/',
+}))
+vi.mock('@voltro/i18n', () => ({
+  defineCatalog: <T,>(c: T): T => c,
+  defineLocale:
+    () =>
+    <T,>(c: T): T =>
+      c,
+  useLocale: () => 'en',
+  useT: (id: string) => id,
+  T: ({ id }: { id: string }) => id,
+}))
+
+const indexMirror = await import('./index')
+const postMirror = await import('./blog/[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).toContain('Blog')
+  })
+})
+
+describe('post mirror — getStaticPaths (locale × slug cross-product)', () => {
+  test('emits one path per non-default locale × post slug', async () => {
+    const paths = await postMirror.getStaticPaths()
+    expect(paths).toEqual(posts.map((post) => ({ params: { locale: 'de', slug: post.slug } })))
+  })
+
+  test('re-exports the base post page + its config exports', () => {
+    expect(typeof postMirror.default).toBe('function')
+    expect(postMirror.renderMode).toBe('static')
+    expect(postMirror.interactive).toBe('islands')
+    expect(typeof postMirror.loader).toBe('function')
+  })
+})

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

@@ -0,0 +1,116 @@
+// @vitest-environment jsdom
+//
+// `/blog/[slug]` — the three static-generation exports: `getStaticPaths`
+// (enumerate slugs), `loader` (fetch this post, `notFound()` for a miss), and
+// `meta(loaderData)` (per-post title). Plus the article render. The page reads
+// `useLoaderData` and renders a `<ReadingProgress>` island — both come from
+// `@voltro/web`, mocked here so `useLoaderData` returns our post and `island`
+// is the identity wrapper.
+
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+import { act, createElement, type ComponentType, type ReactNode } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { posts, type Post } from '../../content/posts'
+import en from '../../locales/en'
+
+const loaderData = vi.fn<() => Post>()
+
+const fill = (msg: string, values?: Record<string, unknown>): string =>
+  values ? msg.replace(/\{(\w+)\}/g, (_, k: string) => String(values[k] ?? `{${k}}`)) : msg
+
+class NotFoundError extends Error {}
+vi.mock('@voltro/web', () => ({
+  useLoaderData: () => loaderData(),
+  // Real `notFound()` throws to abort the loader; a distinct error lets us
+  // assert the miss path without pulling in the router runtime.
+  notFound: (detail?: string) => {
+    throw new NotFoundError(detail)
+  },
+  // Real `island()` wraps the component in a hydration marker; identity keeps
+  // the inner component observable in a unit test.
+  island: (Component: ComponentType<unknown>) => Component,
+  // `withLocalePrefix` (lib/locale) reads useLocation; the post page pins the
+  // locale via useLocale, so any bare path is fine here.
+  useLocation: () => '/',
+}))
+
+// The page renders chrome (back-link, reading-time) via <T>/useLocale — resolve
+// them against the real English catalog with a controllable "current locale".
+vi.mock('@voltro/i18n', () => ({
+  defineCatalog: <T,>(c: T): T => c,
+  defineLocale:
+    () =>
+    <T,>(c: T): T =>
+      c,
+  useLocale: () => 'en',
+  T: ({ id, values }: { id: string; values?: Record<string, unknown> }) =>
+    fill((en as Record<string, string>)[id] ?? id, values),
+}))
+
+const { default: BlogPost, getStaticPaths, loader, meta } = 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(() => {
+  loaderData.mockReset()
+})
+
+afterEach(() => {
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+})
+
+describe('blog [slug] — getStaticPaths', () => {
+  test('enumerates one path per post', async () => {
+    const paths = await getStaticPaths()
+    expect(paths.map((p) => p.params.slug)).toEqual(posts.map((p) => p.slug))
+  })
+})
+
+describe('blog [slug] — loader', () => {
+  test('returns the matching post for a known slug', async () => {
+    const post = await loader({ params: { slug: 'hello-static' } } as never)
+    expect(post.slug).toBe('hello-static')
+    expect(post.title).toContain('zero JavaScript')
+  })
+
+  test('throws notFound for an unknown slug', async () => {
+    await expect(loader({ params: { slug: 'nope' } } as never)).rejects.toBeInstanceOf(
+      NotFoundError,
+    )
+  })
+})
+
+describe('blog [slug] — meta', () => {
+  test('builds a per-post title + description from the loader data', () => {
+    const post = posts[0]!
+    const m = meta({ loaderData: post })
+    expect(m.title).toContain(post.title)
+    expect(m.description).toBe(post.excerpt)
+  })
+})
+
+describe('blog [slug] — render', () => {
+  test('renders the post title, meta line, and each body paragraph', () => {
+    const post = posts[1]!
+    loaderData.mockReturnValue(post)
+    render(createElement(BlogPost))
+    expect(container.querySelector('article h1')?.textContent).toBe(post.title)
+    expect(container.textContent).toContain(`${post.readingMinutes} min read`)
+    const paras = post.body.split('\n\n')
+    expect(container.querySelectorAll('article p').length).toBeGreaterThanOrEqual(paras.length)
+  })
+})

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

@@ -0,0 +1,69 @@
+// A dynamic route — `/blog/<slug>` — pre-rendered STATICALLY, one HTML
+// file per post. Three exports make that work:
+//
+//   • getStaticPaths  → enumerate which slugs to build (from the content
+//                        source; point it at a CMS/DB in a real app).
+//   • loader          → fetch THIS post's data; runs at build per slug.
+//   • meta(loaderData)→ per-post <title>/<description> baked into the HTML.
+//
+// `interactive: 'islands'` hydrates ONLY the <ReadingProgress> island; the
+// article itself is inert HTML.
+
+import type { ReactNode } from 'react'
+import { useLoaderData, notFound, type LoaderFn, type PageMeta } from '@voltro/web'
+import { T, useLocale } from '@voltro/i18n'
+import { posts, type Post } from '../../content/posts'
+import { withLocalePrefix } from '../../lib/locale'
+import ReadingProgress from '../../components/ReadingProgress.island'
+
+export const renderMode = 'static' as const
+export const interactive = 'islands' as const
+
+// Which concrete paths to pre-render. Every returned `params` becomes one
+// built HTML file; un-enumerated slugs are simply not built (→ 404).
+export const getStaticPaths = async (): Promise<Array<{ params: { slug: string } }>> =>
+  posts.map((post) => ({ params: { slug: post.slug } }))
+
+// Runs at build time for each enumerated slug. Returning `notFound()` skips
+// the artifact at build / 404s at runtime — defensive, though getStaticPaths
+// only ever feeds us slugs that exist.
+export const loader: LoaderFn<Post> = async ({ params }) => {
+  const post = posts.find((p) => p.slug === params.slug)
+  if (!post) return notFound(`post ${params.slug}`)
+  return post
+}
+
+// `meta` as a function of the loader data → correct per-post <title> in the
+// pre-rendered HTML (great for SEO + social cards). The title/description are
+// POST CONTENT, not chrome, so they are the same on `/blog/x` and `/de/blog/x`
+// — no per-locale variant needed here.
+export const meta = ({ loaderData }: { loaderData: Post }): PageMeta => ({
+  title: `${loaderData.title} — {{capProjectName}}`,
+  description: loaderData.excerpt,
+})
+
+export default function BlogPost(): ReactNode {
+  const post = useLoaderData<Post>()
+  // The active locale (from the layout's URL provider) keeps the "all posts"
+  // link on the current language.
+  const locale = useLocale()
+  return (
+    <main>
+      <ReadingProgress />
+      <p>
+        <a href={withLocalePrefix('/', locale)}>
+          <T id="post.backToList" />
+        </a>
+      </p>
+      <article>
+        <h1>{post.title}</h1>
+        <p className="muted">
+          {post.date} · <T id="post.readingTimeRead" values={{ minutes: post.readingMinutes }} />
+        </p>
+        {post.body.split('\n\n').map((para, i) => (
+          <p key={i}>{para}</p>
+        ))}
+      </article>
+    </main>
+  )
+}

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

@@ -0,0 +1,100 @@
+// @vitest-environment jsdom
+//
+// `/` blog index — a static list page. Two things worth testing:
+//   1. `meta({ locale })` is localized — it reads the REAL catalog via
+//      getCatalog, so we assert en vs de descriptions directly (no mock).
+//   2. the rendered list shows localized chrome + locale-prefixed links. The
+//      page pulls chrome from @voltro/i18n (<T>, useLocale); we mock those to
+//      resolve against the real catalogs for a controllable "current locale",
+//      so the assertions are genuine localized strings. Post titles/excerpts
+//      come from the real content source and are NOT translated.
+
+import { afterEach, describe, expect, test, vi } from 'vitest'
+import { act, createElement, type ReactNode } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { posts } from '../content/posts'
+import en from '../locales/en'
+import de from '../locales/de'
+
+const catalogs: Record<string, Record<string, string>> = { en, de }
+let currentLocale = 'en'
+
+// Minimal ICU-ish interpolation: replace {key} with values[key].
+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,
+  useT: (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: 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)
+  })
+}
+
+afterEach(() => {
+  currentLocale = 'en'
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+})
+
+describe('index — config + localized meta', () => {
+  test('is a static page with zero client JS', () => {
+    expect(renderMode).toBe('static')
+    expect(interactive).toBe('none')
+  })
+
+  test('meta() returns a localized title + description per locale', () => {
+    expect(meta({ locale: 'en' }).title).toContain('Blog')
+    expect(meta({ locale: 'en' }).description).toContain('pre-rendered')
+    expect(meta({ locale: 'de' }).description).toContain('vorgerenderter')
+  })
+
+  test('meta() falls back to the default (en) catalog for an unknown locale', () => {
+    expect(meta({ locale: 'zz' }).description).toContain('pre-rendered')
+  })
+})
+
+describe('index — localized render', () => {
+  test('lists every post, newest first, with bare links + English chrome (en)', () => {
+    currentLocale = 'en'
+    render(createElement(Index))
+    const links = Array.from(container.querySelectorAll('.post-list a'))
+    expect(links).toHaveLength(posts.length)
+    // Newest-first: the 2025-02-03 post precedes the 2025-01-15 one.
+    expect(links[0]!.getAttribute('href')).toBe('/blog/cms-to-ssg')
+    expect(links[links.length - 1]!.getAttribute('href')).toBe('/blog/hello-static')
+    expect(container.textContent).toContain(`${posts.length} posts`)
+  })
+
+  test('prefixes post links with /de and renders German chrome (de)', () => {
+    currentLocale = 'de'
+    render(createElement(Index))
+    const links = Array.from(container.querySelectorAll('.post-list a'))
+    expect(links[0]!.getAttribute('href')).toBe('/de/blog/cms-to-ssg')
+    expect(container.textContent).toContain(`${posts.length} Beiträge`)
+  })
+})

package/templates/apps/frontend-static-blog/src/pages/index.tsx

@@ -0,0 +1,58 @@
+// Blog index, mounted at `/` (default locale) and mirrored at `/de` by
+// src/pages/[locale]/index.tsx. The post LIST is pure content — no
+// interactivity — so it ships zero JavaScript: `interactive = 'none'` strips
+// every framework <script> from the rendered HTML. The list is read from the
+// same content source the [slug] pages + getStaticPaths use.
+//
+// `meta` is a FUNCTION of `{ locale }` — that's what localises each variant's
+// <title> / <description> in the pre-rendered HTML. Post titles/excerpts are
+// CONTENT (src/content/posts.ts) and are NOT translated; only the chrome
+// (heading, count line, reading-time label) comes from the catalogs.
+
+import type { ReactNode } from 'react'
+import type { PageMeta } from '@voltro/web'
+import { T, useLocale } from '@voltro/i18n'
+import { posts } from '../content/posts'
+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'],
+  }
+}
+
+// Newest first — sort a copy so the source array stays stable.
+const byDateDesc = [...posts].sort((a, b) => b.date.localeCompare(a.date))
+
+export default function Index(): ReactNode {
+  const locale = useLocale()
+  return (
+    <main>
+      <h1>
+        <T id="home.heading" />
+      </h1>
+      <p className="muted">
+        <T id="home.postCount" values={{ count: posts.length }} />
+      </p>
+      <ul className="post-list">
+        {byDateDesc.map((post) => (
+          <li key={post.slug}>
+            <a href={withLocalePrefix(`/blog/${post.slug}`, locale)}>{post.title}</a>
+            <p>
+              <span className="muted">
+                {post.date} · <T id="post.readingTime" values={{ minutes: post.readingMinutes }} />
+              </span>
+              {' — '}
+              {post.excerpt}
+            </p>
+          </li>
+        ))}
+      </ul>
+    </main>
+  )
+}