Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/_bmad-output/specs/M30-i18n.md
T

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
LP-9
LP-10
LP-12
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