@voltro/cli 0.1.0

package/templates/agent-docs/internationalization.md

@@ -0,0 +1,359 @@
+# Internationalization
+
+> Voltro's i18n layer (@voltro/i18n) — an opinionated wrap over react-intl, auto-wired from a single app.config.ts field, with cookie + Accept-Language locale resolution.
+
+
+
+---
+
+<!-- source: en/i18n/overview.md -->
+## Overview
+
+_Voltro's i18n layer (@voltro/i18n) — an opinionated wrap over react-intl, auto-wired from a single app.config.ts field, with cookie + Accept-Language locale resolution._
+
+Voltro ships internationalization in **`@voltro/i18n`** — an opinionated, thin wrap over [`react-intl`](https://formatjs.io/docs/react-intl/) plus framework auto-wiring. A web app gets a working `<I18nProvider>` from a single field in `app.config.ts`. You never write the provider, and you never import `@voltro/i18n` in your layout.
+
+The public surface is intentionally small — `<I18nProvider>`, `<T>`, `useT`, `useTFn`, `useLocale`, `defineCatalog`, `defineLocale`. Power users who need an API the wrap doesn't expose (custom formatters, rich-text with React-element values, `IntlProvider`'s `timeZone` / `formats` props) `import { … } from 'react-intl'` directly. The wrap is **opt-in, not lock-in** — the library is in your `node_modules`, the wrap is optional.
+
+## When to enable
+
+Set `locales` in `app.config.ts` **the moment** your app ships more than one user-facing language, or expects to soon. The infrastructure has **zero cost when `locales` is unset** — no provider is generated, no bundle overhead. Enabling early avoids a painful retro-fit when the first translation request lands.
+
+Don't enable just because the app *could* theoretically be translated. The framework's empty-i18n state is fine for English-only apps, and adding the wiring later is a one-config-field change.
+
+## Setup — auto-wiring
+
+```typescript
+// apps/<project>/<app>/app.config.ts
+export default {
+  type:  'web' as const,
+  name:  'myApp',
+  port:  5191,
+  // Codes the app SHIPS catalogs for. Every code listed here MUST
+  // have a corresponding `src/locales/<code>.ts` file or boot fails.
+  locales: ['en', 'de'] as const,
+  // Fallback locale when no cookie / Accept-Language matches a
+  // supported one. MUST be in `locales`. Pick your source-of-truth
+  // language — typically English.
+  defaultLocale: 'en' as const,
+}
+```
+
+The framework's generated `.framework/app.tsx` wraps the Router in `<I18nProvider>` automatically. You don't write the provider yourself; you don't import `@voltro/i18n` in your layout. Each code in `locales` must have a matching `src/locales/<code>.ts` catalog file — a missing file fails boot, not silently at runtime.
+
+## Locale resolution order
+
+Server-side, the active locale is determined by, in priority order:
+
+1. **`voltro:lang` cookie** — the user's explicit choice (written by `@voltro/ui-shadcn`'s ProfileMenu).
+2. **`Accept-Language` header** — the browser/OS preference, q-weighted and sorted per RFC 4647.
+3. **`defaultLocale`** — last-resort fallback.
+
+The resolved locale is **guaranteed** to be one of the codes in `locales`. Any unsupported value (a cookie pointing at a code you no longer ship, a browser asking for `xx-YY`) falls through to the next signal. RFC 4647 lookup strips subtags one segment at a time — `de-CH-1996` → `de-CH` → `de` — so a `de` catalog serves a `de-CH` browser.
+
+The client side mirrors #1 (cookie) and #3 (default) for hydration safety. `Accept-Language` is **server-only** because `navigator.languages` can diverge from what the server saw, which would cause a hydration mismatch.
+
+See [Catalogs](/docs/i18n/catalogs) for the type-safe catalog convention and the component hooks, and [URL strategies](/docs/i18n/url-strategies) for cookie-only vs URL-prefix routing.
+
+
+
+---
+
+<!-- source: en/i18n/catalogs.md -->
+## Catalogs & hooks
+
+_Type-safe message catalogs with defineCatalog + defineLocale (parity-enforced), reading translations with useT / <T> / useLocale, ICU placeholders, and the react-intl escape hatch._
+
+A **catalog** is a flat `Record<string, string>` of message ID → ICU MessageFormat template. Voltro picks flat-string format (instead of react-intl's `{ defaultMessage, description }` objects) because translation tools (Crowdin / Lokalise / Phrase) import flat string maps natively, the format diffs cleanly in code review, and the base catalog *is* the source of truth — `defaultMessage` becomes redundant.
+
+## Catalog files — type-safe convention
+
+```typescript
+// src/locales/en.ts — base catalog, source of truth
+import { defineCatalog } from '@voltro/i18n'
+
+export default defineCatalog({
+  'header.cta':     'Get started',
+  'home.greeting':  'Hello, {name}',
+  'errors.network': 'Connection lost. Retry?',
+} as const)
+```
+
+```typescript
+// src/locales/de.ts — MUST mirror en exactly
+import { defineLocale } from '@voltro/i18n'
+import en from './en'
+
+export default defineLocale<typeof en>()({
+  'header.cta':     'Loslegen',
+  'home.greeting':  'Hallo, {name}',
+  'errors.network': 'Verbindung verloren. Erneut versuchen?',
+})
+```
+
+`defineCatalog` is an identity function that pins the catalog's literal-key type. `defineLocale<typeof en>()` returns a **curried** function whose argument **must mirror the base catalog's keys exactly** — missing or extra keys fail at `tsc --noEmit`, not at runtime. This is what prevents "translation drift", where non-base locales silently fall out of sync as the base catalog grows.
+
+This parity check is the whole point of having a base catalog. **Don't skip `defineLocale<typeof en>()`** for non-base catalogs — plain `defineCatalog(...)` works but loses the type-level enforcement.
+
+## ICU placeholders
+
+Keep ICU MessageFormat placeholders **identical across locales** — `react-intl` validates them at render time. That covers simple interpolation (`{name}`) and the full ICU surface — plurals, select, ordinals:
+
+```typescript
+// en.ts
+export default defineCatalog({
+  'cart.items': '{count, plural, one {# item} other {# items}}',
+} as const)
+```
+
+```typescript
+// de.ts
+export default defineLocale<typeof en>()({
+  'cart.items': '{count, plural, one {# Artikel} other {# Artikel}}',
+})
+```
+
+**Don't roll your own ICU MessageFormat.** Pluralization, gender, and ordinals across 50+ languages is a solved problem; reimplementing it produces bugs that only surface in specific locales (Turkish dotted-i, Arabic plurals, Finnish cases).
+
+## Reading translations in components
+
+```tsx
+import { useT, useTFn, T, useLocale } from '@voltro/i18n'
+
+// JSX form — preserves rich-text capabilities (component injection).
+<T id="home.greeting" values={{ name: 'Mario' }} />
+
+// Imperative form — for non-JSX contexts (aria-label, placeholder,
+// document.title, toast). Returns a plain string.
+const cta = useT('header.cta')
+const greeting = useT('home.greeting', { name: 'Mario' })
+
+// Function form — capture once, replay inside helpers / list maps /
+// conditional branches without N useIntl() calls per render.
+const t = useTFn()
+const labels = items.map((i) => t('cart.items', { count: i.count }))
+
+// Active locale code (for switching CSS rules, locale-aware date
+// pickers, etc.).
+const locale = useLocale()
+```
+
+- **`<T id="…" />`** — JSX form. Use this whenever you're rendering a string into the tree; it preserves rich-text (React-element values).
+- **`useT(id, values?)`** — imperative form returning a plain string, for non-JSX call sites: `placeholder`, `aria-label`, `document.title`, toasts, error messages.
+- **`useTFn()`** — returns a `(id, values?) => string` translator the component captures once. Use when one component needs `t` inside helper functions or `.map()` callbacks — `react-intl` runs once, the closure replays.
+- **`useLocale()`** — the active locale code, as React state inside the provider.
+
+## The react-intl escape hatch
+
+For features the wrap doesn't expose — custom formatters, `Intl` options, rich-text with React-element values — import from `react-intl` directly:
+
+```tsx
+import { useIntl, FormattedMessage, FormattedNumber, FormattedDate } from 'react-intl'
+```
+
+The wrap deliberately doesn't re-export everything, to keep the framework's blessed API small. The library is already in your `node_modules`.
+
+## Anti-patterns
+
+- **Don't bake locale-specific strings into shadcn primitives, hooks, or anything in `packages/*`.** Strings live in the consuming app's `src/locales/`. Framework and kit code stay string-free.
+- **Don't read the cookie directly in components.** Use `useT` / `useLocale` — the active locale is React state, not browser state, inside the provider.
+- **Don't use translated strings as React keys** or as switch discriminators. Use IDs / enums for control flow; translations are presentation only.
+- **Don't translate code samples in markdown.** Comments inside code fences stay in the source language — readers copy code as-is, and translated identifiers don't compile.
+
+
+
+---
+
+<!-- source: en/i18n/url-strategies.md -->
+## URL strategies
+
+_Cookie-only vs URL-prefix routing (Strategy A / B), the URL-prefix integration sketch, resolveLocale on the /server subpath, the voltro:lang / voltro:theme cookie convention._
+
+There are two ways an i18n app can encode the active locale. Pick **one**, based on what the app's URLs are *for*.
+
+## Strategy A — cookie-only (default for product apps)
+
+- All locales are served from the **same** URL (`/dashboard`, `/settings`).
+- The `voltro:lang` cookie + `Accept-Language` determine which catalog renders.
+- The ProfileMenu's language switch — or the standalone `<LocaleSwitcher>` from `@voltro/ui-shadcn` — writes the cookie and reloads.
+- Use when URLs are **functional** (`/dashboard/projects/42/deployments`) and don't need to encode the language. This is most apps.
+
+This is the zero-config default — the framework's auto-wired `<I18nProvider>` is cookie-driven, so Strategy A needs nothing beyond setting `locales` in `app.config.ts`.
+
+## Strategy B — URL-prefix (default for docs / marketing)
+
+- The default locale lives at the **bare** path (`/docs/foo`).
+- Other locales **prepend** `/<code>` (`/de/docs/foo`).
+- Each translated page has its own crawlable URL → better SEO, shareable language-specific links.
+- Use when URLs **are** the product — search engines index them, links get shared with specific language intent.
+- Requires extra wiring in the layout (below).
+
+The two strategies can coexist across sibling apps: voltro-cloud's dashboard uses cookie-only; its docs app (the one you're reading) uses URL-prefix.
+
+## Render mode constrains the choice
+
+Strategy A isn't always *available* — it depends on how the page renders. Cookie i18n only shows the chosen language two ways: (1) the page **hydrates** on the client (`interactive: 'full'`, the default) and re-renders from the cookie, or (2) the page is **`ssr` / `isr`** and the server resolves the cookie per request.
+
+A page that is `renderMode: 'static'` **and** `interactive: 'none'` / `'islands'` runs neither — its HTML is pre-rendered once in the default locale and never re-renders. Cookie i18n there is a **dead switcher**: it writes the cookie, reloads, and shows the same default-language HTML. Zero-JS static sites and islands pages therefore **must** use Strategy B, whose `[locale]` mirrors make `voltro build` pre-render one HTML file per locale — genuinely bilingual with no client JS.
+
+| Page | i18n strategy |
+| --- | --- |
+| hydrated (`interactive: 'full'`) or `ssr` / `isr` | Strategy A (cookie) works |
+| `static` + `interactive: 'none'` / `'islands'` | Strategy B (URL-prefix) required |
+
+The init-templates follow exactly this split: the hydrated/SSR shells (`app`, `blank`, `spa`, `ssr`, `ssr-api`, `admin`, `dashboard`) ship cookie i18n; the static/islands ones (`landing`, `docs`, `static-blog`, `changelog`, `contact`) ship URL-prefix i18n.
+
+## URL-prefix integration (Strategy B)
+
+The framework's auto-wired `<I18nProvider>` is cookie-driven. For URL-prefix routing you need an **inner** provider that's URL-driven, so client-side navigation between `/docs/x` and `/de/docs/x` swaps the catalog without a full reload.
+
+```tsx
+// src/lib/locale.ts
+import { useLocation } from '@voltro/web'
+
+export const SUPPORTED = ['en', 'de'] as const
+export const DEFAULT = 'en'
+type Locale = (typeof SUPPORTED)[number]
+
+const isSupported = (v: string): v is Locale =>
+  (SUPPORTED as ReadonlyArray<string>).includes(v)
+
+export const localeFromPathname = (p: string): Locale => {
+  const m = /^\/([a-z]{2})(?:\/|$)/.exec(p)
+  return m && isSupported(m[1]!) ? m[1] as Locale : DEFAULT
+}
+
+export const useUrlLocale = (): Locale => localeFromPathname(useLocation())
+
+export const withLocalePrefix = (path: string, locale: string): string => {
+  if (locale === DEFAULT) return path
+  const p = path.startsWith('/') ? path : `/${path}`
+  return p === '/' ? `/${locale}` : `/${locale}${p}`
+}
+
+export const stripLocalePrefix = (p: string): string => {
+  const m = /^\/([a-z]{2})(\/.*|$)/.exec(p)
+  return m && isSupported(m[1]!) ? (m[2] || '/') : p
+}
+```
+
+```tsx
+// src/pages/layout.tsx
+import { I18nProvider } from '@voltro/i18n'
+import en from '../locales/en'
+import de from '../locales/de'
+import { useUrlLocale, DEFAULT } from '../lib/locale'
+
+const CATALOGS = { en, de } as const
+
+const Body = ({ children }) => {
+  // EVERY useT() / <T> in here reads from the inner provider
+  // (URL-driven). useLocation in useUrlLocale triggers re-render
+  // on client-side nav → inner provider re-renders with the new
+  // catalog → all useT lookups update.
+  return <>{children}</>
+}
+
+export default function Layout({ children }) {
+  const locale = useUrlLocale()
+  return (
+    <I18nProvider locale={locale} messages={CATALOGS[locale]} defaultLocale={DEFAULT}>
+      <Body>{children}</Body>
+    </I18nProvider>
+  )
+}
+```
+
+Pair this with locale-prefixed page files: `src/pages/[locale]/index.tsx`, `src/pages/[locale]/docs/[...slug].tsx`, etc. Each re-exports the default-locale query's component, which reads `useUrlLocale()` to decide which catalog data to query.
+
+Reference implementations: `voltro-dev/apps/voltro-dev/docs/` (URL-prefix on dynamic + static content) and `voltro-dev/apps/voltro-dev/landing/` (URL-prefix on a pure static marketing site — 10 default-locale pages, 10 locale-prefixed mirrors, one combined `voltro build` run).
+
+## SSG emission per locale — what `voltro build` does for you
+
+When `locales` is set in `app.config.ts` AND the page tree includes `[locale]/…` mirror files, `voltro build` automatically emits per-locale static HTML at the URL-prefixed paths:
+
+```
+dist/index.html                        ← default locale (en)
+dist/de/index.html                     ← de mirror
+dist/features/foo/index.html           ← default locale
+dist/de/features/foo/index.html        ← de mirror
+```
+
+Each variant ships with the right `<I18nProvider>`-wrapped body **and** the right per-locale `<title>` / `<meta description>` / `<link rel="canonical">` / OG tags — **if** the page's `meta` is exported as a function of `({ locale })`. With a plain static `meta: PageMeta` object, the body is correctly localised but the head tags stay default-locale on every variant.
+
+```tsx
+// src/pages/features/foo.tsx — meta as a function of locale
+import { getCatalog } from '../lib/locale'
+import { localeCanonicalUrl, ogTags, standardLinks } from '../lib/seo'
+
+export const meta = ({ locale }: { readonly locale: string }) => {
+  const c = getCatalog(locale)
+  const title = c['seo.features.foo.title'] as string
+  const description = c['seo.features.foo.description'] as string
+  return {
+    title,
+    description,
+    canonical: localeCanonicalUrl('/features/foo', locale),
+    tags: ogTags({ title, description }),
+    links: standardLinks('/features/foo'),
+  }
+}
+```
+
+The `meta(ctx)` callback runs once per (page × locale) at build time. The `ctx.locale` value comes from `params.locale` for the `[locale]/…` mirror routes; for the bare-path variant it's the app's `defaultLocale`.
+
+### Mechanism
+
+At build time the SSG pipeline pre-loads every catalog and wraps each rendered page in a per-locale `<I18nProvider>`. The `useT()` calls inside pages, layouts, and shared components resolve against the active locale's catalog — no IntlProvider context error, no client-side flash of untranslated content. This is invariant: it fires whether you set `locales` for client-routing reasons (Strategy A: cookies) or full SSG (Strategy B: URL-prefix).
+
+The `[locale]/…` mirror is the trigger for SSG **output** — without mirror files, only the default-locale URLs are emitted (the framework won't guess that `/de/foo` should also exist). With mirror files, their `getStaticPaths` enumerate which locale-prefixed paths to render, and the build produces one HTML file per (page × locale) combination.
+
+### Mirror file boilerplate
+
+12 lines per page. Re-export the canonical page's `default`, `renderMode`, `interactive`, `meta`, plus a `getStaticPaths` that enumerates non-default locales:
+
+```tsx
+// src/pages/[locale]/features/foo.tsx
+import { SUPPORTED_LOCALES, DEFAULT_LOCALE } from '../../../lib/locale'
+export { default } from '../../features/foo'
+export { renderMode, interactive, meta } from '../../features/foo'
+
+export const getStaticPaths = async (): Promise<
+  Array<{ params: { locale: string } }>
+> =>
+  SUPPORTED_LOCALES
+    .filter((l) => l !== DEFAULT_LOCALE)
+    .map((locale) => ({ params: { locale } }))
+```
+
+Cloud-docs and voltro-dev both use this exact pattern — see them for the lib/locale.ts helpers (`SUPPORTED_LOCALES`, `DEFAULT_LOCALE`, `getCatalog`, `useUrlLocale`, `withLocalePrefix`, `stripLocalePrefix`).
+
+## Server-side resolution — the `/server` subpath
+
+```typescript
+import { resolveLocale } from '@voltro/i18n/server'
+
+// In any SSR-side layout, lib, or middleware:
+const locale = resolveLocale({
+  cookieHeader: ssr.headers.cookie,
+  acceptLanguageHeader: ssr.headers['accept-language'],
+  supported: ['en', 'de'],
+  defaultLocale: 'en',
+})
+```
+
+`resolveLocale` is what the framework's auto-wired entry uses under the hood — exposed here for consumers who need locale info **before** the React tree mounts: setting a `lang` attribute on `<html>`, emitting `hreflang` link tags, picking a locale-specific OG image. It applies the same priority order — cookie → `Accept-Language` → default — and the returned locale is guaranteed to be in `supported`.
+
+The `/server` subpath is convention. Both that path and the main entry are pure JS (no Node-only APIs); the split exists so future server-only helpers stay out of browser bundles.
+
+## Cookie convention
+
+The framework reads + writes **`voltro:lang`** for the active language choice (lowercase IETF tag: `en`, `de`, `fr-CA`). `@voltro/ui-shadcn`'s ProfileMenu and the framework's auto-wired resolver agree on this name — **don't pick a different one in app code.**
+
+For theme the parallel cookie is **`voltro:theme`** (values `'system' | 'light' | 'dark'`). Both are managed by the kit's ProfileMenu out of the box; the helpers live in `@voltro/ui-shadcn` (`THEME_COOKIE`, `LANG_COOKIE`, `getCookie`, `setCookie`, `deleteCookie`, `parsePreferenceCookies`, `applyTheme`).
+
+## Anti-patterns
+
+- **Don't mix strategies within one app.** Pick cookie-only *or* URL-prefix per app; mixing them produces ambiguous canonical URLs and broken language switching.
+- **Don't read `Accept-Language` on the client.** It's server-only — `navigator.languages` can diverge from what the server saw and cause a hydration mismatch.
+- **Don't invent your own cookie name.** The kit and the resolver only agree on `voltro:lang` / `voltro:theme`.