86 lines
5.5 KiB
Markdown
86 lines
5.5 KiB
Markdown
# Agent-Anweisungen für Wegwichtel
|
|
|
|
Diese Datei vor jeder Änderung am Projekt lesen. Sie gilt für das gesamte
|
|
Repository. Da sie unter `docs/agents/` liegt, muss ihr Pfad in Übergaben und
|
|
Agent-Aufträgen ausdrücklich genannt werden; eine automatische Suche nach
|
|
einer `AGENTS.md` im Projektverzeichnis findet sie dort nicht.
|
|
|
|
## Ablage der Dokumentation
|
|
|
|
- Markdown mit Agent-Anweisungen, Entwicklungsvorgaben und offenen
|
|
Entwicklungsaufgaben ausschließlich unter `docs/agents/` ablegen.
|
|
- Markdown für Anwender und Betrieb ausschließlich direkt unter `docs/` ablegen.
|
|
- Keine eigenen Markdown-Dateien im Projektverzeichnis oder neben Werkzeugen
|
|
und ausgelieferten Bibliotheken anlegen. Links nach Umzügen aktualisieren.
|
|
- Bei Übergaben die relevanten Markdown-Dateien im Repository mit ihren
|
|
aktuellen Pfaden ausdrücklich nennen, insbesondere diese Datei sowie
|
|
`docs/agents/I18N.md`, `docs/agents/GPX-Aufzeichnung.md` und
|
|
`docs/agents/TODO-MODERATION.md`.
|
|
|
|
# Wegwichtel: Sprache der App
|
|
|
|
GPX-Änderungen berücksichtigen `GPX-Aufzeichnung.md`: Stationen sind `wpt`,
|
|
Aufzeichnungen sind `trkpt`, der Server normalisiert zu `rtept`. Fehlende
|
|
Koordinaten bleiben gespeichert und bearbeitbar; keine Ersatzkoordinaten erfinden.
|
|
Die GPX-Dateien sind die einzige Quelle der Routenpunkte und berechneten
|
|
Routenwerte. SQLite speichert davon nur Min-/Max-Grenzen für die Näheresuche.
|
|
Schemaänderungen immer auch mit der Startprüfung an einer vorhandenen,
|
|
frisch erzeugten Testdatenbank prüfen.
|
|
|
|
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.
|
|
- Ausnahme: Impressum und Datenschutzerklärung bleiben ausschließlich statisch
|
|
auf Deutsch in `public/index.html` und tragen `lang="de"`. Ihre Texte und
|
|
Kontaktangaben gehören nicht in Sprachdateien und erhalten keine i18n-Attribute.
|
|
Auch ihre Dialogüberschriften bleiben beim Sprachwechsel auf Deutsch.
|
|
- 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.
|