Files
HiveGrid-Wireframes/hivegrid-cloud/_bmad-output/specs/M30-i18n.md
T

357 lines
16 KiB
Markdown

---
module: 30
title: i18n / Mehrsprachigkeit
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-9, LP-10, LP-12]
spec_style: requirements-pur
---
# Modul 30 — i18n / Mehrsprachigkeit
> **Detail-Spec gemäß LP-9 + LP-12.** Phase 1 nur DE-Locale befüllt, aber die Library wird extrem sauber gebaut, damit Sprache in Phase 2 wirklich kostenlos erweiterbar ist (DeepL-Pipeline für DE→EN/TR/PL). **Architektur-Vorschrift AV #4: alle Strings extern, kein hartkodierter Text irgendwo.**
## Themenblöcke
```
A. Architektur-Grundsätze (was muss / was darf nicht)
B. Datei-Struktur & Locale-Format
C. Datenmodell (User-Spracheinstellung, Tenant-Default-Sprache)
D. Sprachauflösung (welche Sprache wird wann gewählt)
E. Inhaltliche Trennung: UI-Strings vs. Tenant-Inhalte
F. Outbound-Communication (Email/WhatsApp/Push)
G. Settings-Routen (User + Tenant)
H. Permissions
I. Phase 2 / spätere Features
```
---
## Block A — Architektur-Grundsätze
### A.1 — Pflicht-Vorschriften
1. **Kein hartkodierter User-facing Text** im gesamten Codebase. Jeder String, der in der UI sichtbar ist, jede Email-Vorlage, jeder Klartext-Hinweis, jede Validierungs-Fehlermeldung läuft über die i18n-Library.
2. **Keine String-Konkatenation für Sätze** (verhindert Übersetzbarkeit). Alle Sätze als komplette Locale-Keys mit Platzhaltern.
3. **Pluralisierung über ICU-Format** (nicht über if/else im Code), damit andere Sprachen mit anderen Plural-Regeln (z.B. PL hat 3 Plural-Formen) problemlos funktionieren.
4. **Datums-, Zeit- und Zahlenformate** über `Intl`-API mit User-Locale (DE-Format Default), nicht hartkodiert.
5. **Lint-Regel im Build:** harte Strings in JSX/TSX-Komponenten und Server-Code-Pfaden, die nicht in einer Allowlist (technische Logs, IDs, etc.) stehen, blockieren den Build.
6. **Keine direkten Übersetzungen-on-the-fly** in Phase 1 — alle Texte sind statisch in Locale-Files definiert (LP-10: Klartext-Diagnostik = fest formuliert, nicht KI-on-the-fly).
### A.2 — Was NICHT i18n-pflichtig ist (bewusst exkludiert)
- **Technische Identifier** (Permission-IDs, Pipeline-Stage-Slugs, Activity-Type-Enums, etc.)
- **Datenbankinhalte** (Custom-Felder-Labels, Tag-Namen, Pipeline-Stage-Display-Names, Form-Texte) — siehe Block E.2
- **System-Logs / Sentry-Fehler** (English Default, technisch nicht user-facing)
- **API-Response-Body-Felder** (technische Schlüsselnamen, nicht user-facing)
- **Email-Adressen, URLs, Domains**
---
## Block B — Datei-Struktur & Locale-Format
### B.1 — Datei-Struktur
```
app/i18n/
├── de.json (Phase 1 — voll befüllt)
├── en.json (Phase 2 — DeepL-generiert, manuell reviewt)
├── tr.json (Phase 2)
├── pl.json (Phase 2)
└── index.ts (Loader-Logic, Type-Generation)
```
**Standard-Format:** flache JSON-Strukturen mit Punkt-Notation als Pfad oder verschachtelte Objekte (Implementierungs-Detail). Beispiel-Konvention:
```
{
"common.save": "Speichern",
"common.cancel": "Abbrechen",
"tasks.title": "Aufgaben",
"tasks.empty_state": "Keine offenen Aufgaben — schöne Sache.",
"tasks.deadline_overdue_singular": "{count} Aufgabe überfällig",
"tasks.deadline_overdue_plural": "{count} Aufgaben überfällig"
}
```
### B.2 — Key-Konventionen
- **Namespacing pro Modul:** `tasks.*`, `crm.contacts.*`, `auth.login.*`, etc.
- **Key-Sprache: Englisch in lowercase + underscore/dot**, damit Code-Lesbarkeit in jeder UI-Sprache gleich
- **Wiederverwendbare Bausteine:** `common.save`, `common.cancel`, `common.delete`, `common.archive`, etc.
- **Klartext-Fehlermeldungen** (LP-10): eigener Namespace `errors.*` mit Lösungs-Hinweis-Sub-Keys (`errors.payment_failed.headline`, `errors.payment_failed.body`, `errors.payment_failed.action_label`)
- **Lange Texte (Email-Templates, mehrzeilige Klartext-Hinweise):** als zusammenhängende Strings, kein Composing aus mehreren Keys
### B.3 — Locale-Validierung im Build
- **Vollständigkeits-Check:** alle Keys, die in `de.json` existieren, müssen in jeder anderen befüllten Locale auch existieren (Build-Fail bei Lücken in `en.json`/`tr.json`/`pl.json` ab Phase 2)
- **Keine Waisen-Keys:** Keys, die in keinem Code-Pfad referenziert werden, werden im Build markiert (Warning)
- **Type-Generation:** TypeScript-Types werden aus `de.json` (Master-Locale) generiert; tippt der Code einen falschen Key, gibt es Compile-Error
### B.4 — Master-Locale = DE
- Phase 1: nur `de.json` befüllt
- Andere Locale-Files können in Phase 1 leer/teilbefüllt existieren — Fallback auf DE bei fehlendem Key (LP-12: Sprache kostenlos erweiterbar)
- Fallback-Verhalten: bei fehlendem Key in gewünschter Sprache → automatisch DE-Wert; im Dev-Mode mit Debug-Marker, in Prod silent
---
## Block C — Datenmodell
### C.1 — User-Spracheinstellung
Bestehendes `User`-Feld (siehe Modul 27):
- `language` (Enum: `de | en | tr | pl`, Default `de` in Phase 1, in Phase 1 effektiv nur `de` wählbar)
- `timezone` (IANA-Zeitzonen-String, Default `Europe/Berlin`)
- `date_format_preference` (Enum: `auto | iso | de | us`, Default `auto` — folgt Locale-Standard)
**Setzbar in:** `/{tenant}/settings/profile/`
### C.2 — Tenant-Default-Sprache
Neues `Tenant`-Feld:
- `default_language` (Enum: `de | en | tr | pl`, Default `de`)
- Anwendung: User ohne explizite Spracheinstellung erbt Tenant-Default; Outbound-Communications an Empfänger ohne hinterlegte Spracheinstellung (z.B. Endkunden-Emails an neue Leads) nutzen Tenant-Default
**Setzbar in:** `/{tenant}/admin/general/` (erfordert `tenant.admin`)
### C.3 — Contact-Spracheinstellung (siehe Modul 1)
Bestehendes `Contact`-Feld:
- `language` (Enum: `de | en`, Default `de` in Phase 1) — für Outbound-Kommunikation an den Kontakt
In Phase 2 erweitert auf `de | en | tr | pl`.
### C.4 — Keine separate Locale-DB-Tabelle
Locale-Inhalte sind **statisch in JSON-Files**, nicht in DB. Begründung:
- Performance (kein DB-Roundtrip pro String)
- Versionierung in Git
- Build-Validation möglich
- Ausschließlich Tenant-Inhalte (siehe Block E.2) sind in DB; die werden nicht als Locale-Strings behandelt
---
## Block D — Sprachauflösung
### D.1 — Auflösungs-Reihenfolge (UI)
Beim Rendern einer User-Session:
1. Wenn User eingeloggt + `User.language` gesetzt → diese Sprache
2. Sonst: `Tenant.default_language` (falls in Tenant-Kontext)
3. Sonst: Browser-Header `Accept-Language` (für nicht-eingeloggte Routen wie `/login`, `/signup`, `/help`, Booking-Pages, Forms)
4. Sonst: `de` (Plattform-Fallback)
### D.2 — Auflösungs-Reihenfolge (Outbound an Empfänger)
Beim Versand einer Email/WhatsApp/Push-Notification an einen Empfänger:
1. Wenn Empfänger ein User ist + `User.language` gesetzt → diese
2. Wenn Empfänger ein Contact ist + `Contact.language` gesetzt → diese
3. Sonst: `Tenant.default_language`
4. Sonst: `de`
### D.3 — Sprache pro Request festlegen
- Server-Loader setzt Sprache am Anfang jedes Requests basierend auf D.1
- Components erhalten Sprache über Context/Hook (z.B. `useTranslation`/`t(key)`)
- SSR rendert sofort korrekt ohne Flash-of-DE
### D.4 — Sprache wechseln
- User wechselt Sprache in `/settings/profile/` → sofort wirksam, Reload-Free
- Cookie/Session speichert Sprache (für Konsistenz nach Logout/Re-Login: Wert kommt nach Login direkt aus `User.language` aus DB)
- Non-Logged-In: Sprache via Header-Switcher in Public-Pages (z.B. Help-Center, Booking-Page) änderbar; Auswahl in Cookie für Session
---
## Block E — Inhaltliche Trennung
### E.1 — UI-Strings (i18n-pflichtig)
Alles, was im Code als Text steht und in der UI gerendert wird:
- Button-Labels, Form-Labels, Headlines, Body-Texte
- Validierungs-Fehlermeldungen
- Klartext-Hinweise (LP-10)
- Email-Template-Texte (Plattform-eigene Templates: Welcome, Passwort-Reset, Einladung, Notifications, etc.)
- Push-Notification-Texte
- Help-Center-Artikel-Titel und Default-Inhalt (siehe Modul 38, Phase 1 nur DE)
### E.2 — Tenant-Inhalte (NICHT i18n-pflichtig)
Daten, die der Tenant selbst eingibt — werden in der **Tenant-Sprache** gespeichert und so angezeigt, wie eingegeben:
- Custom-Felder-Labels und -Optionen (Modul 1, Block F)
- Tag-Namen (Modul 1, Block H)
- Pipeline-Stage-Namen (Modul 3, Modul 4)
- Form-Builder-Inhalte: Form-Titel, Feld-Labels, Hilfetexte (Modul 5)
- Booking-Page-Beschreibungen (Modul 6)
- Deal-/Projekt-Templates
- Notizen, Beschreibungen
- Email-Marketing-Kampagnen-Inhalte (Modul 10)
- Automation-Regel-Namen
- HR-Hub-Ankündigungen (Modul 14)
**Begründung:** Diese Inhalte sind tenant-eigene Geschäftsdaten. Multi-Sprach-Support für Tenant-Inhalte (z.B. Pipeline-Stage in DE + EN) ist explizit Phase-2-Thema (siehe I.).
**Tenant-Sprache als Dateneingabe-Sprache:** Der Tenant gibt Custom-Felder/Tags/Pipeline-Stages in der Sprache ein, in der seine Mitarbeiter arbeiten. Wenn ein Tenant mehrsprachige Teams hat, ist das in Phase 1 ein offener Punkt — Workaround: Eingabe in DE oder EN, andere lesen mit.
### E.3 — System-Daten (DE-fix)
Plattform-eigene Default-Daten, die beim Tenant-Anlegen geseedet werden (SHK-Template-Rollen, SHK-Custom-Felder, Default-Pipeline-Stages, Default-Tags) sind in Phase 1 **fix in DE**. Phase 2: Templates haben übersetzte Versionen pro Locale, beim Seeding wird die passende Version genommen je nach `Tenant.default_language`.
---
## Block F — Outbound-Communication
### F.1 — Email
- **Plattform-eigene Templates** (Welcome, Passwort-Reset, MA-Einladung, Notification-Digest, etc.): pro Locale-File ein Template-Set; bei Versand wird Empfänger-Sprache aufgelöst (D.2) und passendes Template gerendert
- **Tenant-eigene Email-Marketing-Kampagnen** (Modul 10): Tenant erstellt Inhalt selbst, in Tenant-Sprache; in Phase 1 keine Multi-Sprach-Variante pro Kampagne (Phase 2 möglich: Variante pro Locale + Empfänger-Auflösung)
- **Plattform-Footer in Email** (Impressum-/AGB-Links, „Powered by HiveGrid"): über Locale-Files
### F.2 — WhatsApp (Phase 2 — Modul 11)
- Analog Email: Plattform-Templates über i18n-Library, Tenant-Templates eingegeben in Tenant-Sprache
- WhatsApp-Business-Templates müssen pro Sprache bei Meta einzeln approved werden — Spec-Detail in Modul 11
### F.3 — Push (Modul 22)
- Plattform-Push-Texte: über Locale-Files
- Empfänger-Sprache via D.2 aufgelöst
- Title + Body separat übersetzt; Deep-Link bleibt sprach-unabhängig
### F.4 — In-App-Notifications (Modul 22)
- Über Locale-Files; Sprache des **lesenden** Users (D.1), nicht des erzeugenden Users
- Beispiel: User A (DE) erstellt Task für User B (EN) → User B sieht Notification auf EN
---
## Block G — Settings-Routen
### G.1 — User-Profile-Settings (`/{tenant}/settings/profile/`)
**Spracheinstellung:**
- Auswahl-Komponente für Sprache (Phase 1: nur DE auswählbar — andere Sprachen in der UI sichtbar als „Coming soon", Phase 2 freigeschaltet)
- Auswahl-Komponente für Zeitzone
- Auswahl-Komponente für Datums-Format-Präferenz
- Sofortige Anwendung ohne Reload
**Permission:** keine eigene — jeder eingeloggte User kann sein eigenes Profil bearbeiten.
### G.2 — Tenant-General-Settings (`/{tenant}/admin/general/`)
**Tenant-Default-Sprache:**
- Auswahl-Komponente für `Tenant.default_language`
- Klartext-Hinweis: *„Diese Sprache wird verwendet für: Outbound-Emails an Empfänger ohne eigene Spracheinstellung, Default für neue User, System-Texte für nicht-eingeloggte Besucher (Booking-Pages, Forms)."*
**Permission:** `tenant.admin`.
### G.3 — Help-Center (Modul 38) und Public-Pages
- URL-Struktur enthält Sprachsegment für öffentliche Seiten: `/help/{lang}/{slug}` (Phase 1 effektiv nur `/help/de/...`)
- Booking-Pages und Forms erben Tenant-Default-Sprache; Endkunde sieht Sprach-Switcher (Phase 2 mehr Optionen)
---
## Block H — Permissions
### Permission-IDs
i18n hat **keine eigenen** Permissions. Anwendungen:
- User-Spracheinstellung in `/settings/profile/` → kein Permission-Gate (eigenes Profil)
- Tenant-Default-Sprache in `/admin/general/` → `tenant.admin`
### Klartext-Fehler
- User wählt Sprache, die in Phase 1 noch nicht befüllt ist: Fallback auf DE silent in Prod; im Dev-Mode Hinweis *„Lokalisierung für [Sprache] ist noch nicht vollständig — Fallback auf Deutsch."*
- Tenant-Admin wechselt `default_language` zu nicht-befüllter Sprache: Klartext-Warnung *„Die Sprache [Sprache] ist noch nicht vollständig verfügbar. Bestehende User behalten ihre Sprache; neue System-Texte fallen auf Deutsch zurück."*
---
## Block I — Klartext-Hinweise (zentral)
- Sprache erfolgreich gewechselt: *„Sprache geändert."*
- Fehlende Locale: siehe oben
- Browser-Header zeigt unbekannte Sprache: silent Fallback DE
---
## Phase 2 / spätere Features
### I.1 — DeepL-Pipeline (DE → EN/TR/PL)
- Build-Step: alle DE-Keys werden via DeepL-API automatisch übersetzt
- Generierte Locale-Files werden manuell reviewt (Glossary für Fachbegriffe SHK, Plattform-Begriffe wie „Tenant", „Workspace")
- Glossary in Repo gepflegt (CSV oder JSON)
- Re-Translation nur für geänderte Keys (Diff-basiert)
- DeepL-API-Quota: monatlich, in CI/CD getrackt
### I.2 — Chat-Auto-Übersetzung (KI-Killer-Feature)
- Team-Chat (Modul 13): User schreibt in seiner Sprache, andere User sehen automatisch in ihrer Sprache übersetzt
- Beispiel: PL-Monteur schreibt Polnisch, Büro liest Deutsch
- Pro Nachricht: Original gespeichert, Übersetzung on-the-fly per LLM (LP-13: EU-Provider Mistral/Scaleway)
- Toggle pro User: „Nachrichten in meine Sprache übersetzen" (Default an, in mehrsprachigen Tenants)
- Kennzeichnung: Übersetzung als solche markiert mit Original-Anzeige auf Klick
### I.3 — Multi-Sprach-Tenant-Inhalte
- Custom-Felder-Labels mit Übersetzungen pro Locale (Tenant-Admin pflegt mehrere Sprachversionen)
- Pipeline-Stage-Namen mit Übersetzungen
- Form-Builder-Forms mit Übersetzungs-Modus für Endkunden-Forms
- Email-Marketing-Kampagnen-Varianten pro Locale, Empfänger-Auflösung wie F.1
### I.4 — Sprache pro Endkunden-Form
- Endkunde wählt Sprache auf öffentlicher Form-Page
- Form-Builder erlaubt Übersetzungen der Feld-Labels und Hilfetexte
### I.5 — Help-Center mehrsprachig
- Plattform-Help-Center mit voll lokalisierten Artikeln (Modul 38)
- DeepL für Erst-Übersetzung, manueller Review
### I.6 — Datenformate erweitert
- Lokale Telefon-Format-Anzeige (E.164 + lokales Display)
- Lokale Adress-Formate (US-Adressen vs. DACH-Adressen)
- Lokale Währungsanzeigen pro User-Präferenz
### I.7 — Sprache für KI-Outputs (LLM-Gateway)
- LLM-Antworten werden in User-Sprache erzeugt (Prompt-Suffix mit Sprach-Anweisung)
- RAG-Suche kann sprachübergreifend matchen (Multi-Lingual-Embeddings)
---
## Architektur-Vorschriften (Querschnitt)
- **AV #4 (LP-12) — Alle Strings extern:** kein hartkodierter Text, Lint-Regel im Build (Block A.1)
- **LP-9 — Spec-Tiefe:** Architektur-Vorschrift hier auf Modul-Ebene konkret beschrieben
- **LP-10 — Klartext-Diagnostik:** alle Fehler-Texte in `errors.*`-Namespace mit Headline + Body + Action-Label
- **LP-12 — Sprache kostenlos erweiterbar:** Library so sauber gebaut, dass Phase 2 nur Locale-Files + DeepL-Pipeline benötigt, kein Code-Refactor
- **LP-13 — EU-Stack:** DeepL ist EU-Anbieter, kompatibel; KI-Übersetzungen Phase 2 ausschließlich über EU-LLM-Gateway
---
## Detail-Spec-Status: DRAFT
Erste vollständige Detail-Spec für Modul 30. **Vor Bau:** Verifizierung der Lint-Regel-Strenge mit Noah (Allowlist für technische Strings). Bei Implementierung dann konkrete i18n-Library-Wahl (z.B. `react-i18next` aus altem Codebase weiternutzen oder Alternative), Build-Pipeline für DeepL Phase 2 separat speccen.
**Offene Detail-Punkte (nicht-blockierend):**
- Konkrete i18n-Library-Wahl (Implementierungs-Detail)
- Lint-Regel-Allowlist-Spec
- DeepL-Glossary-Format (Phase 2)
- Konkretes Cookie-Schema für Non-Logged-In-Sprach-Persistierung
**Abhängige Module:**
- Alle UI-Module (jedes Modul liefert seine Locale-Keys)
- Modul 22 (Notifications) — Empfänger-Sprach-Auflösung
- Modul 10 (Email-Marketing) — Phase 2 Multi-Sprach-Kampagnen
- Modul 13 (Chat) — Phase 2 Auto-Übersetzung
- Modul 38 (Help-Center) — Phase 2 Multi-Sprach-Artikel