14 KiB
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-modusist NICHT dieses Modul (das ist Hell/Dunkel-Modus). Modul-Spec „M30" = Milestones M028+M029.
- Achtung Numerik-Stolperfalle: Das Repo-Milestone-Verzeichnis
- Pflichtenheft-Block: Block 1, Modul 30 (
_bmad-output/pflichtenheft/blocks/block1.mdAbschnitte 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
Tenant.default_languagefehlt (Spec C.2).Tenant(…/prisma/schema/accounts.prisma:129) hat nurtheme/themeConfig, kein Sprach-Default. → Neues Feld + Forward-Only-Migration. Blockt M028 (Mandanten-Default in Auflösungs-Reihenfolge).User.timezoneundUser.date_format_preferencefehlen (Spec C.1). Nirgends inprisma/schema/*.prismaeintimezone/dateFormat-Feld (grep leer). → Zwei neueUser-Felder. Profil-Picker für Zeitzone/Datumsformat (G.1) gibt es noch nicht (nur Locale-Picker vorhanden).- Resolution-Order unvollständig (Spec D.1 / Pflichtenheft 30.2.4). Boilerplate-
remixI18Nextlöst Cookie → Browser-Accept-Language→ Fallbackde. Es fehlt derTenant.default_language-Schritt (User > Tenant > Browser > DE) und das Lesen vonUser.localeaus DB nach Login. → Resolver-FunktionresolveLocale(user, tenant, browser, default)inapp/locale/**ergänzen (M028 Slice-Hinweis nennt exakt diese Signatur). - Outbound-Empfänger-Auflösung D.2 fehlt (Pflichtenheft 30.2.5).
mail-translator.server.tslöst nur eine übergebene Locale; die Kette „User.language > Contact.language > Tenant.default_language > de" muss neu gebaut werden. SetztContact.languagevoraus (Modul 1 — im aktuellen Schema kein CRM-Contact-Modell mitlanguagegefunden). - TR/PL-Locales fehlen (Spec B.4 / Pflichtenheft 30.1.6). Nur
de+enin…/apps/web/public/locales/. Phase-1-Pflicht ist nur DE befüllt — abersupportedLocalesmusstr/plals Ziel-Sprachen kennen (für „Coming soon"-Anzeige G.1 und Fallback-Hinweise H/I). Der Parity-Checker würde leeretr/pl-Files als Divergenz melden → Strenge anpassen (Spec B.4: andere Locales dürfen Phase 1 teilbefüllt sein, Fallback auf DE). errors.*-Namespace-Struktur (Spec B.2 / LP-10). Boilerplate hat zwar einenerrors-Namespace, aber die geforderte Sub-Key-Strukturerrors.<x>.headline / .body / .action_labelist HiveGrid-spezifisch und muss als Konvention etabliert/befüllt werden (koppelt an M002 Error-Catalog).- 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.
- 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, Permissiontenant.admin). Tenant-Default-Picker existiert noch gar nicht. - Public-Page-Sprach-Switcher mit Cookie (Spec G.3 / M029 / Pflichtenheft 30.4.2).
LocaleSelector.tsxexistiert als Footer-Switcher, aber dedizierter Public-Page-Switcher (Help/help/{lang}/…, Booking, Forms) mithttpOnly:false, samesite:lax-Cookie (M029-Slice-Hinweis) ist neu. URL-Sprachsegment/help/{lang}/{slug}(Integration-Contracts §3) noch nicht verdrahtet. .server.ts-Memory-Blocker prüfen. Boilerplate nutzti18next.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).- 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 inpackages/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):
packages/i18nals@hivegrid/i18nübernehmen (Plurale, Intl-Formatter,useTranslate, ICU) — unverändert.- 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. - 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). - 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).