fix sonar findings and translation structure

2026-10-01 16:31:46 +02:00
parent 2b42507f13
commit 5c4d20bd1d
30 changed files with 1753 additions and 894 deletions
@@ -0,0 +1,49 @@
+# Texte und Sprachen
+
+Die Sprachdateien `public/js/texts-de.js` und `public/js/texts-en.js` enthalten
+jeweils die generische Klasse `WegwichtelTexts`. Beide Dateien verwenden dieselben
+Schlüssel und registrieren ihren Katalog mit der eigenen Sprachkennung in
+`Wegwichtel.TextCatalogs`. Es gibt keine sprachabhängigen Klassennamen.
+
+Die App lädt beide Kataloge vor `i18n.js`. Beim Start wird die erste unterstützte
+Sprache aus `navigator.languages` gewählt; ohne diese Liste wird
+`navigator.language` verwendet. Regionale Varianten wie `en-GB` oder `de-DE`
+verwenden den passenden Grundkatalog. Passt keine Sprache, wird der erste
+geladene Katalog verwendet: in der App Deutsch. Einzelne fehlende Übersetzungen
+fallen ebenfalls auf diesen Katalog zurück. Wird nur eine Sprachdatei eingebunden,
+funktioniert sie allein und bildet den Fallback.
+
+## Verwendung
+
+Schlüssel beschreiben die Funktion, nicht den Wortlaut. Zusammengehörige Texte
+liegen in verschachtelten Abschnitten; der Aufruf verwendet Punkte als Trennung.
+
+```js
+Wegwichtel.I18n.t('app.no-route');
+Wegwichtel.I18n.t('bootstrap-loader.error.start-error');
+Wegwichtel.I18n.t(`bootstrap-loader.steps.${step}`);
+Wegwichtel.I18n.t('media.image.count', { count: 2 });
+```
+
+`bootstrap-loader.steps` ist nach den stabilen Schrittkennungen aufgebaut:
+`storage`, `jquery`, `jquery-ui`, `modules`, `server`, `routes` und `location`.
+Die Zuordnung benötigt keine zusätzliche Liste von Nachrichtenschlüsseln.
+
+HTML verwendet `data-i18n`, `data-i18n-title`, `data-i18n-aria-label`,
+`data-i18n-placeholder` und `data-i18n-alt`. Deutsche Standardtexte werden mit
+`node scripts/localize-html.js` aus dem Katalog ins HTML übernommen. Dadurch
+stehen Beschriftungen bereits vor dem Laden der Skripte bereit. Nach Änderungen
+die erzeugte `public/index.html` mit ins Repository übernehmen.
+
+Zum gezielten Prüfen kann `Wegwichtel.I18n.setLanguage('en')` aufgerufen werden.
+Das aktualisiert feste Beschriftungen. Bereits aufgebaute dynamische Ansichten
+müssen neu aufgebaut werden; die automatische Startauswahl erfolgt vor ihrem
+ersten Aufbau. Ein sichtbarer Sprachschalter ist nicht enthalten.
+
+Die Tests prüfen beide Kataloge, Platzhalter und Pluralformen, Browserpräferenzen,
+den Betrieb mit nur einer Sprachdatei, deutsche HTML-Standardtexte und englische
+App-Meldungen. Nutzerinhalte wie Streckennamen werden nicht übersetzt.
+
+SonarQube prüft auch die Sprachdateien auf Probleme und Testabdeckung. Nur die
+Duplikaterkennung nimmt `public/js/texts-*.js` aus: Übersetzungskataloge müssen
+dieselbe Struktur haben und sind keine mehrfach implementierte Programmlogik.