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 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.