Internationalisierung (i18n)

Das Scriptlib ou.sp.I18n stellt die Bausteine bereit, mit denen eine Lösung so gebaut wird, dass eine neue Sprache nur noch das Übersetzen der Locale-Datei erfordert. Es ist also kein Eingriff in Installer-, Workflow- oder Gadget-Code notwendig.

Die verbindlichen Regeln dazu stehen in ADR 025 — Regeln für Internationalisierung in Documents. Diese Seiten beschreiben, wie die Regeln mit den Hilfsfunktionen umgesetzt werden.

Das Prinzip in drei Schritten

1. Definieren: Alle Strings einer Lösung stehen als verschachteltes JavaScript-Objekt in einem globalPropertiesLocales-Skript — eine Referenzsprache (de) plus je eine typisierte Kopie pro weiterer Sprache.
2. Installieren: Bei Installation und Upgrade wird pro Sprache eine Globale Eigenschaft im Properties-Format erzeugt (installLocales).
3. Verwenden: Im Code wird nie ein Klartext-String geschrieben, sondern ein Locale-Key aufgelöst — serverseitig über t/TError/insertStatusEntry, clientseitig über das I18n-Clientmodul, und in Documents-Konfigurationen über das pf:-Präfix.

Überblick über die Funktionen

Funktion	Zweck	Seite
installLocale, installLocales, LocaleShape	Locale-Datei definieren und installieren	Locale-Dateien
t, createT, makeT	Übersetzen mit Auto-Completion	Übersetzen
TError, createTError	Fehlermeldungen, inkl. technischer Ursache	Fehlermeldungen
insertStatusEntry, createInsertStatusEntry	Mappenstatus-Einträge	Statuseinträge
I18n.t, I18n.createT	Clientseitig in Gadgets und Userexits	Clientseitig
expectLocalesConsistent	Locale-Dateien im Test prüfen	Testen

Welche Strings übersetzt werden müssen

Nicht jeder String, den ein Nutzer sehen könnte, muss lokalisiert werden. Entscheidend ist die Handlungsrelevanz: Würde eine Übersetzung ändern, was der Nutzer als Nächstes tut?

Übersetzen

• Validierungsmeldungen, fehlende Pflichtfelder, fachliche Prüfregeln — der Nutzer liest, korrigiert, speichert erneut.
• Alle Labels, die in der Oberfläche erscheinen: Feld- und Registerbezeichnungen, Buttons, Spaltenköpfe, Tooltips, Dialogtitel, Workflow-Aufgaben und -Entscheidungskommentare, Statuseinträge, Benachrichtigungen.

Nicht übersetzen

• Technische, nicht handlungsrelevante Fehler — Datenbankverbindungsfehler, ein fehlschlagendes docFile.sync(), unerwartete Exceptions. Der nächste Schritt (erneut versuchen, Support kontaktieren) ist in jeder Sprache derselbe. Muss der Nutzer trotzdem informiert werden, gehört ein generischer übersetzter Rahmen davor und der unübersetzte technische Grund dahinter — siehe cause.
• Log-Ausgaben (Logging.use(...), otrLogger) — entwicklerseitig, erreichen keinen Endnutzer.
• Installer- und Upgrade-Meldungen (appendToResultSuccess/appendToResultError).
• Nicht-natürlichsprachliche Literale — Tabellen- und Spaltennamen, HTML-Ids und CSS-Klassen, Skriptnamen, interne Codes, JSON-Keys, Feldnamen.
• Testdateien (*.spec.ts, *.test.ts).