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

14 KiB
Raw Blame History

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).