From 5872593b014e527ef884ea89053f9cf191edf5dc Mon Sep 17 00:00:00 2001 From: Citali Date: Wed, 11 Feb 2026 12:09:43 +0100 Subject: [PATCH] docs(i18n): add conventions guide and wire docs navigation --- TODO.md | 3 +- docs/.vitepress/config.mts | 1 + docs/product-engineering/i18n-baseline.md | 2 +- docs/product-engineering/i18n-conventions.md | 86 ++++++++++++++++++++ docs/product-engineering/index.md | 1 + 5 files changed, 91 insertions(+), 2 deletions(-) create mode 100644 docs/product-engineering/i18n-conventions.md diff --git a/TODO.md b/TODO.md index cafc08d..e9f14f8 100644 --- a/TODO.md +++ b/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 diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 92e508e..c2f06f8 100644 --- a/docs/.vitepress/config.mts +++ b/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" }, diff --git a/docs/product-engineering/i18n-baseline.md b/docs/product-engineering/i18n-baseline.md index 40cb051..5cdf549 100644 --- a/docs/product-engineering/i18n-baseline.md +++ b/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`. diff --git a/docs/product-engineering/i18n-conventions.md b/docs/product-engineering/i18n-conventions.md new file mode 100644 index 0000000..3c91d1c --- /dev/null +++ b/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` diff --git a/docs/product-engineering/index.md b/docs/product-engineering/index.md index 5735cc1..69ebda1 100644 --- a/docs/product-engineering/index.md +++ b/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)