## Internationalization (i18n) Architecture ### Translation File Structure Store all localized content in the `i18n/` directory, organized first by language and then by page or feature. ```text i18n/ ├── config.ts ├── dictionaries.ts ├── en/ │ ├── common.yaml │ ├── home.yaml │ ├── about.yaml │ └── guides/ │ └── example.yaml ├── de/ │ ├── common.yaml │ ├── home.yaml │ ├── about.yaml │ └── guides/ │ └── example.yaml └── es/ ├── common.yaml ├── home.yaml ├── about.yaml └── guides/ └── example.yaml ``` The page and folder names above are illustrative. Actual files must match the application's pages and features. ### Translation Organization - **Page files:** Each page has a corresponding YAML file containing its localized content, including long-form text, headings, metadata, labels, image descriptions, and captions. - **Shared text:** `common.yaml` contains genuinely shared interface content, such as navigation labels, footer text, and reusable messages. - **Reusable features:** Features with their own localized content may have dedicated YAML files. - **Nested pages:** Nested routes may use matching subfolders. - **Language parity:** All language directories must have corresponding files with matching keys, section identifiers, and data structures. - **Shared identifiers:** Route identifiers, asset paths, technical identifiers, and other nontranslated data remain independent of language files. ### Translation Loading - `i18n/config.ts` defines supported locales, the default locale, and localized URL helpers. - `i18n/dictionaries.ts` provides typed, server-only YAML loading. - YAML content is parsed and validated against shared TypeScript content schemas at build time. - Server Components load the required page and shared content. - Client Components receive only the localized strings they need, rather than importing complete dictionaries. - Shared React components render content for all languages. ### Content Rendering - Designated YAML fields may contain Markdown-formatted text. - A shared Markdown renderer converts these fields into React elements. - Structured YAML sections may reference approved component types, such as articles, diagrams, and callouts. - Section ordering is determined by the YAML content. - Reusable React components control presentation, styling, and behavior. - Content files contain no executable application code, JSX, CSS, or presentation logic. - Raw HTML embedded in Markdown is not rendered. ### Localized Routing - English is the default language and uses unprefixed URLs, such as `/about`. - German uses `/de/`, such as `/de/about`. - Spanish uses `/es/`, such as `/es/about`. - Localized pages share the same underlying rendering components. - Each localized page provides appropriate metadata, canonical URLs, and `hreflang` alternates. - Language switching preserves the equivalent page whenever possible. - Sitemaps include all published language variants. ## Website implementation boundaries - `domain/`: page-content contracts, validation, canonical route inventory, and related-page relationships. No UI or filesystem imports. - `infrastructure/`: server-only filesystem access and YAML parsing. Public content requests must match a canonical route and supported locale. - `application/`: localized navigation and metadata assembly using the domain and content loaders. - `i18n/`: shared locale/URL helpers, server content loader, and localized YAML files. - `components/`: shared presentation. Small Client Components handle disclosure keyboard support, language-link context, copy controls, and localized recovery UI. - `app/(english)/`, `app/(german)/de/`, and `app/(spanish)/es/`: thin explicit locale route adapters. Each has a static locale root layout and optional catch-all page; all three use the same `SiteDocument`, `WebsitePage`, metadata assembly, and recovery components. This keeps the document language fixed for each locale while generating all 111 known pages. No language-specific UI implementation or middleware locale detection is used. - `app/sitemap.ts` and `app/robots.ts`: generated discovery endpoints, using the configured build-time public origin. - `styles/tokens.css`: central theme. CSS Modules consume tokens. Breakpoint thresholds are named in the design implementation documentation; native media queries use literal thresholds because CSS custom properties cannot be used in media conditions. - `diagrams/` and `public/diagrams/`: editable Mermaid sources and generated SVGs. Build colors derive from theme tokens and are converted to inherited CSS variables in the inline assets. Generated inline SVG style attributes are normalized into classes. - `specifications/current/`: maintained current-state website requirements, separate from the preserved human-authored specification under `specifications/`. All known pages are generated at build time. A minimal CommonJS startup adapter delegates requests to Next.js under cPanel Passenger; no domain or product behavior is implemented in that adapter. Local YAML content is the only content source, and filesystem access never enters Client Components. `SITE_URL` is a public build configuration value; the real production origin must be supplied before building for publication. The Next.js configuration is `next.config.mjs`, a directly executable ECMAScript module with JSDoc typing. Production startup does not transpile a TypeScript configuration or load native compiler bindings. This keeps the prebuilt runtime compatible with the hosting account's older GLIBC while preserving the existing configuration settings; native build tooling remains a local build concern. ## HTTP recovery documents The build renders three small standalone recovery documents with React DOM from the same localized YAML and theme tokens. `routing-manifest.json` is generated from the canonical route registry and public assets. The cPanel startup adapter delegates known URLs and Next.js assets to Next.js; `infrastructure/recovery.cjs` returns a generated localized document with HTTP 404 for unknown GET/HEAD requests. This avoids a Next.js 16 initial-error-document limitation where the localized not-found UI is otherwise delivered only through hydration. No new public content route, redirect, dependency, or product business rule is introduced. Framework-level not-found boundaries remain available during development and internal client navigation. The recovery renderer is a standalone HTML artifact, so native `` and stylesheet links are intentional; Next.js document lint rules are disabled only for that renderer. It requires no JavaScript and is served with a restrictive Content Security Policy. Known asset/page routing remains owned by Next.js. The generated manifest prevents a separately maintained route inventory in the startup adapter.