Internationalization

AGENTS.md

@@ -0,0 +1,42 @@
+# Wegwichtel: Sprache der App
+
+Diese Vorgabe des Nutzers gilt für alle künftigen Änderungen an der Oberfläche.
+Die App richtet sich an Grundschulkinder und Menschen ohne technische Vorkenntnisse.
+
+- Schreibe kurze, verständliche Sätze. Sprich die Nutzer mit „du“ an.
+- Erkläre, was eine Aktion bewirkt und was als Nächstes zu tun ist.
+- Verwende durchgängig „Strecke“, „Station“, „Meine Entwürfe“ und „für unterwegs speichern“.
+- Technische Begriffe wie GPX, JSON, Cache, API, OPFS, IndexedDB, Local Storage,
+  Server, Token oder interne Feldnamen gehören nicht in Bedienungstexte,
+  Hilfe, Statusmeldungen, Dateiauswahl-Beschreibungen oder vorgelesene Beschriftungen.
+- Bezeichne einen Wegexport als „Weg als Datei herunterladen“. Erkläre bei Bedarf,
+  dass die Datei für eine andere Wander-App gedacht ist und keine Bilder oder Ton enthält.
+- Verwende „Bilder und Tonaufnahmen“ statt „Medien“, „Zur Prüfung senden“ statt „Upload“
+  und „auf diesem Gerät“ statt „lokal im Browser“.
+- Fehlermeldungen nennen das Problem und einen verständlichen nächsten Schritt.
+  Zeige keine rohen Fehler aus dem Betriebssystem, Netzwerkantworten oder Dateipfade.
+- Vereinfache auch Hilfen zu Daten und Speicher. Behalte wichtige Angaben zu
+  Löschung, Erlaubnissen, Grenzen und Speicher-Schätzungen bei. Mache keine
+  Zusicherungen, die die App nicht einhalten kann.
+- Rechtliche Texte dürfen notwendige Rechtsbegriffe behalten. Erkläre sie einfach;
+  ändere dabei nicht die Bedeutung, Verantwortlichen oder Kontaktdaten.
+- Fachliche Details für Entwicklung und Betrieb gehören in Projekt-Dokumentation
+  und Code-Kommentare. Code-Bezeichner, Dateiformate und Schnittstellen bleiben fachlich präzise.
+- Prüfe neue Texte und angepasste Text-Erwartungen in den vorhandenen Tests.
+
+## Texte und Übersetzungen
+
+- Alle eigenen Bedienungstexte liegen zentral in der Klasse `WegwichtelTextsDe`
+  in `public/js/texts-de.js`. Keine neuen sichtbaren Texte direkt in HTML oder
+  Funktionscode schreiben.
+- JavaScript bezieht Texte über `Wegwichtel.I18n.t(textKey, variables)`.
+  HTML verwendet `data-i18n` bzw. `data-i18n-aria-label`, `data-i18n-title`,
+  `data-i18n-placeholder` und `data-i18n-alt`.
+- Zahlen und Namen sind Platzhalter; ganze Sätze übersetzen, keine Sätze aus
+  deutschen Wortteilen zusammensetzen. Für Mengen Einzahl und Mehrzahl verwenden.
+- Nutzerinhalte wie Streckennamen, Beschreibungen und Aufnahmen nicht automatisch
+  übersetzen oder verändern. Interne Fehlerdiagnosen dürfen technisch bleiben;
+  die sichtbare Meldung muss verständlich sein.
+- Zusätzliche Sprachen über `I18n.register` ergänzen. Fehlende Übersetzungen
+  fallen auf Deutsch zurück. Sprachwechsel aktualisieren feste Beschriftungen;
+  bereits erzeugte dynamische Ansichten bei Bedarf neu rendern.