16 KiB
module, title, phase, status, last_updated, session_source, related_lps, spec_style
| module | title | phase | status | last_updated | session_source | related_lps | spec_style | |||
|---|---|---|---|---|---|---|---|---|---|---|
| 30 | i18n / Mehrsprachigkeit | 1 | detail-spec-draft | 2026-05-08 | brainstorming-session-2026-05-07-2206.md |
|
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
- 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.
- Keine String-Konkatenation für Sätze (verhindert Übersetzbarkeit). Alle Sätze als komplette Locale-Keys mit Platzhaltern.
- 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.
- Datums-, Zeit- und Zahlenformate über
Intl-API mit User-Locale (DE-Format Default), nicht hartkodiert. - 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.
- 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.jsonexistieren, müssen in jeder anderen befüllten Locale auch existieren (Build-Fail bei Lücken inen.json/tr.json/pl.jsonab 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.jsonbefü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, Defaultdein Phase 1, in Phase 1 effektiv nurdewählbar)timezone(IANA-Zeitzonen-String, DefaultEurope/Berlin)date_format_preference(Enum:auto | iso | de | us, Defaultauto— folgt Locale-Standard)
Setzbar in: /{tenant}/settings/profile/
C.2 — Tenant-Default-Sprache
Neues Tenant-Feld:
default_language(Enum:de | en | tr | pl, Defaultde)- 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, Defaultdein 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:
- Wenn User eingeloggt +
User.languagegesetzt → diese Sprache - Sonst:
Tenant.default_language(falls in Tenant-Kontext) - Sonst: Browser-Header
Accept-Language(für nicht-eingeloggte Routen wie/login,/signup,/help, Booking-Pages, Forms) - Sonst:
de(Plattform-Fallback)
D.2 — Auflösungs-Reihenfolge (Outbound an Empfänger)
Beim Versand einer Email/WhatsApp/Push-Notification an einen Empfänger:
- Wenn Empfänger ein User ist +
User.languagegesetzt → diese - Wenn Empfänger ein Contact ist +
Contact.languagegesetzt → diese - Sonst:
Tenant.default_language - 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.languageaus 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_languagezu 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