Files
HiveGrid-Wireframes/hivegrid-cloud/docs/boilerplate-mapping/M30-i18n.md
T

99 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Boilerplate-Abgleich — Modul M30: i18n / Mehrsprachigkeit
- **Modul-ID:** M30 (Spec `_bmad-output/specs/M30-i18n.md`)
- **Name:** i18n / Mehrsprachigkeit
- **Zugehörige Milestones:** M028 (User/Tenant Sprach-Settings + Auflösungs-Reihenfolge), M029 (Sprach-Wechsler + Fallback-Hinweise). Querschnitt-Vorbedingung: M003 (i18n-Pflicht-Wiring).
- **Achtung Numerik-Stolperfalle:** Das Repo-Milestone-Verzeichnis `docs/milestones/M030-hell-dunkel-modus` ist NICHT dieses Modul (das ist Hell/Dunkel-Modus). Modul-Spec „M30" = Milestones M028+M029.
- **Pflichtenheft-Block:** Block 1, Modul 30 (`_bmad-output/pflichtenheft/blocks/block1.md` Abschnitte 30.1–30.6)
- **Reuse-Level:** **HIGH** — vollständige i18n-Library + App-Wiring + CI-Gates bereits vorhanden; HiveGrid füllt vor allem Inhalte (Locale-Keys, TR/PL) ein und ergänzt zwei Datenmodell-Felder + zwei Resolver-Schritte.
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
| --- | --- | --- |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/i18n/` | Eigenständiges `@toolctrl/i18n`-Paket: Locale-Config, ICU-MessageFormat-Plurale, SSR-sichere Intl-Formatter (Zahl/Währung/Datum/RelativeTime/Liste), RTL-Erkennung, `useTranslate`-Factory | **1:1** (Paket nur umbenennen `@toolctrl/i18n`→`@hivegrid/i18n`; Logik unverändert) |
| `…/packages/i18n/src/index.ts` | `defaultLocale="de"`, `supportedLocales=["de","en"]`, `i18nNamespaces`, `i18nConfig`, `isSupportedLocale`, `getDirection`, `isRTL` | **anpassen** — `supportedLocales` auf `["de","en","tr","pl"]` erweitern; Namespaces auf HiveGrid-Module mappen |
| `…/packages/i18n/src/icu/plural.ts` | `formatIcu`, `createIcuFormatter` (FormatJS/CLDR-Plural-Regeln, deckt PL 3-Form-Plurale ab) | **1:1** — erfüllt Spec A.1.3 (ICU-Plural) komplett |
| `…/packages/i18n/src/intl/{number,currency,date,list}.ts` | Locale-explizite Intl-Wrapper, gecacht, SSR-safe | **1:1** — erfüllt Spec A.1.4 (Intl-Formate) |
| `…/packages/i18n/src/useTranslate.ts` | `createUseTranslate(deps)` — react-i18next injiziert (kein harter Dep), automatische ICU-Erkennung | **1:1** |
| `…/apps/web/app/locale/i18next.server.ts` | Server-Loader: `remixI18Next` (remix-i18next), `i18nCookie` (`_i18n`, 30 Tage), `getTranslations(request, ns)`, fs-Backend pro `{{lng}}/{{ns}}.json` | **anpassen** — erfüllt D.3 (Sprache pro Request im Loader) + Cookie-Persistenz (D.4); Resolution-Order erweitern (siehe Lücken) |
| `…/apps/web/app/locale/i18next.global.server.ts` | Globale i18next-Instanz für SSR (verhindert Flash/Hydration-Mismatch, lädt alle Locales synchron vorab) | **1:1** — erfüllt D.3 „SSR rendert sofort korrekt ohne Flash-of-DE" |
| `…/apps/web/app/locale/mail-translator.server.ts` | `getMailTranslator(locale)`, `getMailTranslatorFromRequest(request)`, `resolveMailLocale` (Fallback auf `defaultLocale`), `mail`-Namespace | **anpassen** — Basis für Block F (Outbound-Email i18n); Empfänger-Auflösung D.2 ergänzen (User/Contact/Tenant-Default) |
| `…/apps/web/app/components/ui/selectors/LocaleSelector.tsx` | Sprach-Dropdown, submitted an `/preferences` (`action=setLocale`), iteriert `i18nConfig.supportedLngs` | **als-vorlage** — Public-Page-Switcher (G.3) + Header-Switcher (D.4); UI in HiveGrid-Design neu bauen (Subframe), Logik übernehmen |
| `…/apps/web/app/routes/preferences.tsx` | Root-Action `setLocale`, schreibt Locale-Cookie, Reload-frei | **anpassen** — erfüllt D.4 (Live-Wechsel ohne Reload); zusätzlich `User.locale` in DB persistieren bei eingeloggtem User |
| `…/apps/web/app/modules/users/components/UserProfileSettings.tsx` (Picker referenziert in `…/routes/app.$tenant/settings/profile.locale-picker.test.ts`) | Locale-Picker im User-Profil, `i18nConfig.supportedLngs`, `changedLocale()`, `setLocale`→`/preferences` | **als-vorlage** — Basis für G.1 (`/{tenant}/settings/profile/`); Zeitzone+Datumsformat-Picker fehlen noch |
| `…/scripts/i18n-check.ts` | Locale-Parity-Checker: Key-Divergenz pro Namespace, fehlende/leere Files, **Waisen-Keys** (`unexpected-locale-dir`), **fehlende Source-Keys** (`t("…")` ohne Locale-Eintrag), leere Übersetzungen | **1:1** — erfüllt B.3 (Vollständigkeits-Check, Waisen-Keys, Master=DE) nahezu komplett |
| `…/scripts/verify-hardcoded-strings.mjs` (+ `.test.mjs`) | Build-Lint gegen hartkodierte User-facing Strings über `apps/packages/prisma/server`, mit Allowlist (`reviewedPathPatterns`) | **1:1 / anpassen** — erfüllt A.1.5 (Lint-Regel im Build) + Allowlist-Mechanik (offener Spec-Punkt „Lint-Regel-Allowlist-Spec") |
| `…/scripts/i18n-audit.mjs` + `verify-i18n-hardcoded-baseline.mjs` | Baseline-Scan hartcodierter DE/EN-Strings (zählt, erzwingt nicht — Migrations-Hilfe) | **als-vorlage** — nützlich beim schrittweisen Härten der Lint-Regel |
| `package.json` Script `verify:i18n` | `tsx scripts/i18n-check.ts && node scripts/verify-hardcoded-strings.mjs && eslint --max-warnings=0 packages/ui-*` | **1:1** — fertiges CI-Gate für DoD-Punkt 10 (i18n-Keys Pflicht) |
| `…/apps/web/app/modules/i18n/locale-coherence.test.ts` | Cross-Language-Copy-Leak-Test (DE-Wörter im EN-Catalog etc.) | **als-vorlage** — Inhalt ist boilerplate-spezifisch (Tenant→Konto-Wording), Struktur als Vorlage für HiveGrid-Glossar-Tests |
| `…/apps/web/app/modules/i18n/autogenerated-locale-prune.test.ts` | Prune-Test: Locale-Keys ohne Source-Referenz markieren | **anpassen** — ergänzt Waisen-Key-Erkennung (B.3) |
| `…/apps/web/app/utils/i18n/translateLabel.ts` (+ `.test.ts`) | Helper zum Übersetzen von Label-Keys | **als-vorlage** |
| `…/apps/web/public/locales/{de,en}/*.json` (9 Namespaces: translations, auth, billing, common, crm, emailMarketing, errors, mail, settings) | Befüllte DE+EN-Locale-Files | **als-vorlage** — Struktur/Konvention übernehmen, Inhalte sind ToolCTRL-spezifisch und werden durch HiveGrid-Keys ersetzt |
| `package.json` deps | `i18next ^23`, `react-i18next ^15`, `remix-i18next ^7`, `i18next-fs-backend`, `i18next-http-backend`, `i18next-browser-languagedetector`, `intl-messageformat ^10` | **1:1** — kompletter Stack vorhanden, keine neuen Libs nötig (klärt Spec-offenen-Punkt „i18n-Library-Wahl" → react-i18next ist gesetzt) |
---
## Vorhandene Daten-Modelle
| Modell / Feld | Pfad | Status gegen Spec |
| --- | --- | --- |
| `User.locale` (`String?`) | `…/prisma/schema/accounts.prisma:16` | **vorhanden** — deckt C.1 `language` ab (als freier String, nicht Enum `de\|en\|tr\|pl`). Reicht funktional, ggf. Enum-/Validierung in App-Layer ergänzen |
| `User.lightOrDarkMode` (`String?`) | `…/prisma/schema/accounts.prisma:17` | vorhanden (gehört zu M030 Hell/Dunkel, nicht i18n — nur Kontext) |
| `Tenant` (Modell, Felder `theme`, `themeConfig`) | `…/prisma/schema/accounts.prisma:129` | Tenant existiert, **aber KEIN `default_language`/`locale`-Feld** → siehe Lücken (C.2) |
| `Portal.locale` (`String?`) | `…/prisma/schema/portals.prisma:67` | vorhanden (Customer-Portal-Locale; relevant für Public-Portal-Sprachauflösung) |
| `KnowledgeBase.defaultLanguage` / `.languages` / `Article.language` | `…/prisma/schema/knowledgeBase.prisma:12,16,37,73` | vorhanden — Basis für Help-Center-Mehrsprachigkeit (G.3, Phase 2 / Modul 38) |
| FeatureFlag-Filter-Typ `language.is` | `…/prisma/schema/featureFlags.prisma:37` | vorhanden — Sprache als Targeting-Dimension nutzbar |
**Datenmodell-Fazit:** `User`-Sprache ist da; `Tenant`-Default-Sprache, `User.timezone` und `User.date_format_preference` sind NICHT vorhanden.
---
## Lücken / komplett neu zu bauen
1. **`Tenant.default_language` fehlt** (Spec C.2). `Tenant` (`…/prisma/schema/accounts.prisma:129`) hat nur `theme`/`themeConfig`, kein Sprach-Default. → Neues Feld + Forward-Only-Migration. Blockt M028 (Mandanten-Default in Auflösungs-Reihenfolge).
2. **`User.timezone` und `User.date_format_preference` fehlen** (Spec C.1). Nirgends in `prisma/schema/*.prisma` ein `timezone`/`dateFormat`-Feld (grep leer). → Zwei neue `User`-Felder. Profil-Picker für Zeitzone/Datumsformat (G.1) gibt es noch nicht (nur Locale-Picker vorhanden).
3. **Resolution-Order unvollständig** (Spec D.1 / Pflichtenheft 30.2.4). Boilerplate-`remixI18Next` löst Cookie → Browser-`Accept-Language` → Fallback `de`. Es fehlt der **`Tenant.default_language`-Schritt** (User > **Tenant** > Browser > DE) und das Lesen von `User.locale` aus DB nach Login. → Resolver-Funktion `resolveLocale(user, tenant, browser, default)` in `app/locale/**` ergänzen (M028 Slice-Hinweis nennt exakt diese Signatur).
4. **Outbound-Empfänger-Auflösung D.2 fehlt** (Pflichtenheft 30.2.5). `mail-translator.server.ts` löst nur eine übergebene Locale; die Kette „User.language > Contact.language > Tenant.default_language > de" muss neu gebaut werden. Setzt `Contact.language` voraus (Modul 1 — im aktuellen Schema kein CRM-`Contact`-Modell mit `language` gefunden).
5. **TR/PL-Locales fehlen** (Spec B.4 / Pflichtenheft 30.1.6). Nur `de`+`en` in `…/apps/web/public/locales/`. Phase-1-Pflicht ist nur DE befüllt — aber `supportedLocales` muss `tr`/`pl` als Ziel-Sprachen kennen (für „Coming soon"-Anzeige G.1 und Fallback-Hinweise H/I). Der Parity-Checker würde leere `tr`/`pl`-Files als Divergenz melden → Strenge anpassen (Spec B.4: andere Locales dürfen Phase 1 teilbefüllt sein, Fallback auf DE).
6. **`errors.*`-Namespace-Struktur** (Spec B.2 / LP-10). Boilerplate hat zwar einen `errors`-Namespace, aber die geforderte Sub-Key-Struktur `errors.<x>.headline / .body / .action_label` ist HiveGrid-spezifisch und muss als Konvention etabliert/befüllt werden (koppelt an M002 Error-Catalog).
7. **Fallback-Debug-Marker (Dev) + Klartext-Hinweise** (Spec B.4, H, I.). „Lokalisierung für [Sprache] noch nicht vollständig — Fallback auf Deutsch" (Dev), „Sprache geändert." etc. — als Locale-Keys + Dev-Mode-Marker neu. remix-i18next macht silenten Fallback (Prod ok), Dev-Marker fehlt.
8. **Settings-Routen für HiveGrid-URL-Schema** (Spec G.1/G.2). Boilerplate-Profil-Route liegt unter `app.$tenant/settings/profile`; HiveGrid-Pattern ist `/{tenant}/settings/profile/` und `/{tenant}/admin/general/` (Tenant-Default-Sprache, Permission `tenant.admin`). Tenant-Default-Picker existiert noch gar nicht.
9. **Public-Page-Sprach-Switcher mit Cookie** (Spec G.3 / M029 / Pflichtenheft 30.4.2). `LocaleSelector.tsx` existiert als Footer-Switcher, aber dedizierter Public-Page-Switcher (Help `/help/{lang}/…`, Booking, Forms) mit `httpOnly:false, samesite:lax`-Cookie (M029-Slice-Hinweis) ist neu. URL-Sprachsegment `/help/{lang}/{slug}` (Integration-Contracts §3) noch nicht verdrahtet.
10. **`.server.ts`-Memory-Blocker prüfen.** Boilerplate nutzt `i18next.server.ts` / `i18next.global.server.ts`. Laut User-Memory (S03) ist `.server.ts`-**Re-Export** inkompatibel mit RR7-Client-Build. Diese Dateien sind server-only Logik (kein Client-Re-Export) → vermutlich unkritisch, aber bei Übernahme verifizieren, dass keine Client-Komponente daraus importiert (Component-Extraktion-Regel beachten).
11. **Layer-Trennung (AGENTS.md).** Boilerplate-Locale-Logik liegt in `apps/web/app/locale`. HiveGrid-DoD verlangt VM-Layer + `packages/ui-hivegrid`-Adapter; Locale-Switcher als reusable Component in `packages/ui-hivegrid` (M029-Hinweis) — Adapter neu, Logik aus Boilerplate.
**Explizit NICHT in Phase 1 (Spec 30.5 / Block I.):** DeepL-Pipeline, Auto-Chat-Übersetzung, mehrsprachige Mandanten-Inhalte, mehrsprachiges Help-Center. Boilerplate liefert dafür kein Fundament (außer KnowledgeBase-Sprach-Felder) — korrekt, da out-of-scope.
---
## Empfohlenes Vorgehen
**Phase A — Foundation übernehmen (1:1, schnell):**
1. `packages/i18n` als `@hivegrid/i18n` übernehmen (Plurale, Intl-Formatter, `useTranslate`, ICU) — unverändert.
2. CI-Gate `verify:i18n` (`i18n-check.ts` + `verify-hardcoded-strings.mjs` + ESLint) übernehmen → erfüllt direkt DoD-Punkt 10 + Spec A.1.5/B.3.
3. App-Wiring übernehmen: `i18next.server.ts`, `i18next.global.server.ts` (SSR-Flash-Schutz), `preferences.tsx`-Action (`setLocale` + Cookie). `.server.ts`-Import-Pfade gegen RR7-Client-Build verifizieren (Memory S03).
4. react-i18next-Stack als gesetzte Library-Wahl dokumentieren (schließt Spec-offenen-Punkt).
**Phase B — Datenmodell ergänzen (M028 Vorbedingung):**
5. Migration: `Tenant.default_language`, `User.timezone`, `User.date_format_preference` (Forward-Only + Inverse-SQL-Kommentar). `User.locale` bleibt.
6. `supportedLocales` → `["de","en","tr","pl"]`; `de` als Master. Parity-Checker so konfigurieren, dass teilbefüllte `tr`/`pl` Phase 1 nicht hart blocken (Spec B.4).
**Phase C — Resolver + Outbound (M028 Kern):**
7. `resolveLocale(user, tenant, browser, default)` neu — Tenant-Default-Schritt in die Kette einfügen (D.1).
8. Outbound-Empfänger-Auflösung D.2 in `mail-translator.server.ts`-Erweiterung (User > Contact > Tenant > de). Setzt `Contact.language` aus Modul 1 voraus (Abhängigkeit prüfen).
**Phase D — UI/Settings (M028 G.1/G.2 + M029):**
9. User-Profil-Picker (`/{tenant}/settings/profile/`): Locale-Picker (aus Boilerplate-Vorlage) + neue Zeitzone-/Datumsformat-Picker; „Coming soon" für tr/pl. Reload-free via `/preferences`.
10. Tenant-General-Picker (`/{tenant}/admin/general/`) für `Tenant.default_language`, Permission-Gate `tenant.admin` (M004 `withPermission`).
11. Public-Page-Switcher mit Cookie (`samesite:lax`, nicht-httpOnly) als reusable Component in `packages/ui-hivegrid` (M029); URL-Sprachsegment `/help/{lang}/…` verdrahten.
12. Klartext-Hinweise + Dev-Fallback-Marker als Locale-Keys; `errors.*`-Sub-Key-Struktur (headline/body/action_label) mit M002 koppeln.
**Phase E — Layer-Konformität + Tests:**
13. Locale-Switcher + Picker via VM-Layer + `ui-hivegrid`-Adapter (AGENTS.md A.1–A.5); keine `useLoaderData` in UI-Components.
14. Tests: VM-Builder-Unit-Tests, Smoke-Tests (Sprach-Wechsel live, Public-Booking-Cookie, unvollständiges Test-Locale → 30.6.1-Hinweis), Hot-Swap-Drill, Visual-Snapshot. Parity-/Prune-Tests aus Boilerplate adaptieren.
**Reihenfolge-Kern:** Erst alles aus BP übernehmen (Phase A) → dann die 3 fehlenden DB-Felder + tr/pl (B) → dann die 2 fehlenden Resolver-Schritte (C) → erst danach UI/Settings (D) → Layer/Tests (E).