Wegwichtel/AGENTS.md

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 WegwichtelTexts in public/js/texts-de.js. Keine neuen sichtbaren Texte direkt in HTML oder Funktionscode schreiben.
• Das HTML enthält daraus erzeugte deutsche Standardtexte, damit Beschriftungen vor dem Laden der Skripte vorhanden sind. Nach Änderungen am Textkatalog node scripts/localize-html.js ausführen und public/index.html mit ablegen. Diese erzeugten Texte nicht von Hand ändern; die i18n-Attribute bleiben erhalten.
• 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.
• Sprachdateien heißen public/js/texts-<Sprache>.js und verwenden dieselbe generische Klasse WegwichtelTexts. Sie registrieren sich in TextCatalogs. Die App lädt Deutsch und Englisch und wählt anhand von navigator.languages bzw. navigator.language. Fehlende Übersetzungen fallen auf den ersten geladenen Katalog zurück (in der App Deutsch).
• Verwende kurze, stabile englische Funktionsschlüssel wie app.no-route oder bootstrap-loader.error.start-error. Schlüssel nicht aus dem deutschen Text ableiten. Startmeldungen in bootstrap-loader.steps nach Schritt gruppieren.
• Deutsch und Englisch enthalten dieselben Schlüssel, Platzhalter und Pluralformen. Texte in beiden Sprachen einfach und sinngemäß schreiben. Sprachwechsel aktualisieren feste Beschriftungen; bereits erzeugte dynamische Ansichten bei Bedarf neu rendern.