i18n und Übersetzungen

Zweck

SpeamCore ist von Grund auf mehrsprachig. Pro Mandant koennen Anwender ihre Spracheinstellung individuell wählen, und Inhalte werden in der gewählten Sprache angezeigt — wobei der Datenbestand nur in einer „Pflegesprache" gespeichert wird, sofern Felder nicht explizit als translatable markiert sind.

i18n-Architektur

Frontend (react-i18next)

• Locale-Dateien in speamcore.com/src/locales/<lang-code>/<namespace>.locale.json.
• Namespaces typisch: common, routes, product, checklist, errors, mail, etc.
• 50+ Sprachen unterstützt — pro Sprache muss nicht jeder Namespace komplett übersetzt sein, Fallback auf en greift.
• Schlüssel sind englisch (t("customers"), t("save")).

Die Liste der aktivierten Sprachen kommt aus dem Modell Languages — nur diese erscheinen im Sprachwechsler. Status pro Namespace und Sprache liefert die Sub-Route /languages/translation-status.

Backend (i18next + i18next-http-middleware)

• Library: i18next 23.5.x mit i18next-http-middleware (Code-verifiziert in api.speamcore.com/package.json).
• Genutzt für Fehler-Meldungen und automatische Notifications.
• DE und EN ueblicherweise vollständig; andere Sprachen sporadisch.
• Locale wird über Header (Accept-Language) oder via setLanguageContextMiddleware aus dem Request eingelesen.

Translatable Felder

Manche Daten sollen pro Sprache unterschiedlich sein. SpeamCore loest das auf zwei Wegen:

A) isTranslatable bei Attributen

Auf Attributes gibt es das Flag isTranslatable: boolean. Bei true und type = text|textarea werden Werte pro Sprache in AttributeValue als JSON-Map abgelegt, z. B.:

{
  "de-DE": "Brandschutztuer geprueft",
  "en-US": "Fire-protection door inspected"
}

Anzeige greift auf den Eintrag der aktuellen Locale zu, mit Fallback auf eine Default-Sprache.

B) translationKey bei System-Einträgen

System-Stamm-Daten (z. B. SKR03-Kontenbezeichnungen, Standard-Attribut-Namen, NumberCircle-Hilfstexte) speichern keinen freien name, sondern einen translationKey. Anzeige: i18n.t(translationKey).

Beispiel: System-Attribute haben systemAttribute = true und der name-Anzeige-Wert kommt aus i18n.t(translationKey) statt aus dem freien Feld.

Fallback-Verhalten

Quelle	Fehlt Locale →
react-i18next	Locale en (oder Mandanten-Default)
AttributeValue translatable	Erste in der Map vorhandene Sprache
translationKey	Sichtbarer Schlüssel (zeigt z. B. lng:productGroup an)

Anwender-Setting

Pro Mitarbeiter und Mandant/Client wird language als BCP-47-Locale gespeichert (z. B. de-DE, en-US, fr-FR). Bei Login setzt das FE die Locale auf den Anwender-Wert.

Hinzufuegen einer neuen Sprache

1. Sprachen → + Neu mit code (BCP-47) und name.
2. FE-Locale-Dateien für <code> in src/locales/ erstellen oder aus Vorlage kopieren.
3. Mindestens common und routes übersetzen, damit die Navigation funktioniert.
4. Translation-Status prüfen — /languages/translation-status zeigt Vollstaendigkeits-Prozent pro Namespace.

Berechtigungen

Action	Subject	Wirkung	Keycloak-Rolle
view	Language	Sprachen sehen	APP_SPEAMCORE_VIEW_LANGUAGE
create/update/delete	Language	Sprachen pflegen	APP_SPEAMCORE_CREATE/UPDATE/DELETE_LANGUAGE
view	LanguageTranslationStatus	Status-Sub-Route	APP_SPEAMCORE_VIEW_LANGUAGE_TRANSLATION_STATUS
do	Language (Custom)	Sprachwechsel im FE — typisch für alle freigegeben	APP_SPEAMCORE_DO_LANGUAGE (CUSTOM)`

Wiederverwendbare Konzepte

• Berechtigungen verstehen (CASL)

Verknuepfungen zu Modulen

• Sprachen — Stammdaten und Translation-Status.
• Setup-Wizard — Schritt 1 (Sprache).
• Attribute — isTranslatable-Flag, systemAttribute mit translationKey.
• Mail und Belege — Spracheinstellung wirkt auf Mail-Versand und Beleg-Druck.
• Mitarbeiter und Mandanten/Clients — Profil-Einstellung.

Versionshinweise

• 2026-04-30: Initiale Veroeffentlichung als Querschnitts-Konzept.