docs(i18n): add conventions guide and wire docs navigation

TODO.md

@@ -73,7 +73,7 @@ This file is the single source of truth for roadmap and delivery progress.
 
 - [x] [P1] Docs tool baseline added (`docs/` via VitePress)
 - [x] [P1] RBAC and permission model documentation in docs site
-- [ ] [P2] i18n conventions docs (keys, namespaces, fallback, translation workflow)
+- [x] [P2] i18n conventions docs (keys, namespaces, fallback, translation workflow)
 - [~] [P1] CRUD base patterns documentation and examples
 - [ ] [P1] Environment and deployment runbook docs (dev/staging/production)
 - [ ] [P2] API and domain glossary pages
@@ -206,6 +206,7 @@ This file is the single source of truth for roadmap and delivery progress.
 - [2026-02-10] Admin app now uses a shared shell with permission-aware navigation and dedicated IA routes (`/pages`, `/media`, `/users`, `/commissions`).
 - [2026-02-10] Public app now has a shared site layout (`banner/header/footer`), DB-backed header banner config, and SEO defaults (`metadata`, `robots`, `sitemap`).
 - [2026-02-10] Testing baseline now includes explicit RBAC regression checks, locale-resolution unit tests (admin/web), CRUD service contract tests, and i18n smoke e2e routes.
+- [2026-02-10] i18n conventions are now documented as an engineering standard (`docs/product-engineering/i18n-conventions.md`).
 
 ## How We Use This File
 

docs/.vitepress/config.mts

@@ -22,6 +22,7 @@ export default defineConfig({
           { text: "Better Auth Baseline", link: "/product-engineering/auth-baseline" },
           { text: "CRUD Baseline", link: "/product-engineering/crud-baseline" },
           { text: "i18n Baseline", link: "/product-engineering/i18n-baseline" },
+          { text: "i18n Conventions", link: "/product-engineering/i18n-conventions" },
           { text: "RBAC And Permissions", link: "/product-engineering/rbac-permission-model" },
           { text: "Testing Strategy", link: "/product-engineering/testing-strategy" },
           { text: "Workflow", link: "/workflow" },

docs/product-engineering/i18n-baseline.md

@@ -18,4 +18,4 @@ Current baseline:
 
 - Public app locale is resolved through `next-intl` middleware + cookie.
 - Enabled locales are currently static in code and will later be managed from admin settings.
-- Translation key conventions and workflow docs are tracked in `TODO.md`.
+- Translation key and workflow standards are documented in `i18n-conventions.md`.

docs/product-engineering/i18n-conventions.md

@@ -0,0 +1,86 @@
+# i18n Conventions
+
+## Scope
+
+This document defines translation conventions for both apps in MVP0+.
+
+- Public app i18n: `next-intl` message namespaces and route-level usage
+- Admin app i18n: JSON dictionaries + runtime resolver/provider
+- Shared locale contract: `@cms/i18n` (`de`, `en`, `es`, `fr`; default `en`)
+
+## Locale Policy
+
+- Source of truth: `packages/i18n/src/index.ts`
+- Current enabled locales are code-driven and shared across web/admin.
+- Admin-managed locale toggles are planned for a later MVP.
+
+## Key Naming Conventions
+
+- Use `camelCase` for keys.
+- Group by domain namespace (not by component filename).
+- Keep keys stable; update values, not key names, during copy edits.
+
+### Public app namespaces
+
+- `Layout.*`
+- `Home.*`
+- `LanguageSwitcher.*`
+- Page-specific namespaces, e.g. `About.*`, `Contact.*`
+- Metadata namespace: `Seo.*`
+
+### Admin app namespaces
+
+- `common.*`
+- `auth.*`
+- `dashboard.*`
+- `settings.*`
+
+## Message Structure
+
+- Keep messages as nested JSON objects.
+- Avoid very deep nesting (prefer 2-3 levels).
+- Keep punctuation in translation values, not code.
+- Avoid embedding HTML in message strings.
+
+## Fallback Rules
+
+- Unknown/invalid locale values fallback to default locale `en`.
+- Missing translation key behavior:
+  - Admin: `translateMessage` returns provided fallback, else key.
+  - Public: ensure required keys exist in locale JSON; avoid runtime missing-key states.
+
+## Adding New Translation Keys
+
+1. Add key/value in `apps/*/src/messages/en.json`.
+2. Add equivalent key in `de/es/fr` JSON files.
+3. Use key via translator:
+   - Web: `useTranslations("Namespace")` or `getTranslations("Namespace")`
+   - Admin: `useAdminT()` or server-side `translateMessage(...)`
+4. Add/adjust tests for behavior where relevant.
+
+## Translation Workflow
+
+1. Author English source copy first.
+2. Add keys in all supported locales in same change.
+3. Keep semantic parity across locales.
+4. Run checks:
+   - `bun run check`
+   - `bun run typecheck`
+   - `bun run test`
+5. For route-level i18n behavior changes, run e2e smoke:
+   - `bunx playwright test --grep "i18n smoke"`
+
+## QA Checklist
+
+- Locale switch persists after refresh.
+- Page headings and navigation labels translate correctly.
+- Metadata (`Seo`) strings resolve per locale.
+- No missing-key placeholders visible in UI.
+
+## Related Files
+
+- `apps/web/src/i18n/request.ts`
+- `apps/web/src/i18n/routing.ts`
+- `apps/admin/src/i18n/server.ts`
+- `apps/admin/src/i18n/messages.ts`
+- `packages/i18n/src/index.ts`

docs/product-engineering/index.md

@@ -8,6 +8,7 @@ This section covers platform and implementation documentation for engineers and
 - [Architecture](/architecture)
 - [Better Auth Baseline](/product-engineering/auth-baseline)
 - [RBAC And Permissions](/product-engineering/rbac-permission-model)
+- [i18n Conventions](/product-engineering/i18n-conventions)
 - [Testing Strategy Baseline](/product-engineering/testing-strategy)
 - [Workflow](/workflow)