Add multilingual README documentation - Rename README.md to README_de.md - Create README_en.md with English translation - Create new README.md with overview and language links
This commit is contained in:
511
README_de.md
Normal file
511
README_de.md
Normal file
@@ -0,0 +1,511 @@
|
||||
# Elpatrons Datumsrechner
|
||||
|
||||
[](https://github.com/elpatron/datecalc)
|
||||
[](https://date.elpatron.me)
|
||||
[](https://date.elpatron.me)
|
||||
[](https://date.elpatron.me)
|
||||
[](https://date.elpatron.me)
|
||||
|
||||
Diese moderne Python-Webanwendung (Flask) ermöglicht verschiedene Datumsberechnungen über eine übersichtliche, barrierefreie Weboberfläche.
|
||||
|
||||
## Inhaltsverzeichnis
|
||||
|
||||
- [Demo](#demo)
|
||||
- [Funktionen](#funktionen)
|
||||
- [Installation (lokal)](#installation-lokal)
|
||||
- [Starten der App](#starten-der-app)
|
||||
- [Statistik-Dashboard & Passwortschutz](#statistik-dashboard-stats--passwortschutz)
|
||||
- [Docker (empfohlen für Produktion)](#docker-empfohlen-für-produktion)
|
||||
- [Log-Verzeichnis mounten](#log-verzeichnis-mounten-logs-auf-dem-host-speichern)
|
||||
- [docker-compose Beispiel](#docker-compose-beispiel)
|
||||
- [REST API](#rest-api)
|
||||
- [Tage/Werktage zwischen zwei Daten](#1-tagewerktage-zwischen-zwei-daten)
|
||||
- [Wochentag zu einem Datum](#2-wochentag-zu-einem-datum)
|
||||
- [Kalenderwoche zu Datum](#3-kalenderwoche-zu-datum)
|
||||
- [Start-/Enddatum einer Kalenderwoche](#4-start-enddatum-einer-kalenderwoche)
|
||||
- [Datum plus/minus Tage, Wochen, Monate](#5-datum-plusminus-tage-wochen-monate)
|
||||
- [Statistik](#6-statistik)
|
||||
- [Monitoring & Healthcheck](#7-monitoring--healthcheck)
|
||||
- [Progressive Web App (PWA)](#progressive-web-app-pwa)
|
||||
- [Monitoring & Healthcheck](#monitoring--healthcheck)
|
||||
- [Entwicklung & Hinweise](#entwicklung--hinweise)
|
||||
- [Automatisierte Tests](#automatisierte-tests)
|
||||
- [Hinweise](#hinweise)
|
||||
- [Motivation](#motivation)
|
||||
- [Vibe Coding](#vibe-coding)
|
||||
- [Statistik-Erfassung, Logging](#statistik-erfassung-logging)
|
||||
- [Barrierefreiheit (Accessibility)](#barrierefreiheit-accessibility)
|
||||
- [Code Statistik](#code-statistik)
|
||||
- [Lizenz](#lizenz)
|
||||
|
||||
## Demo
|
||||
|
||||
Datumsrechner Live: [https://date.elpatron.me](https://date.elpatron.me)
|
||||
|
||||
[](https://date.elpatron.me)
|
||||
|
||||
**[Lighthouse](https://en.wikipedia.org/wiki/Lighthouse_(software))-Performance-Score:**
|
||||
|
||||
Die Webanwendung erreicht hervorragende Performance-Werte in allen Kategorien (Performance, Accessibility, Best Practices, SEO).
|
||||
|
||||
[Lighthouse-Ergebnis (PDF)](./lighthouse/lighthouse-score.pdf)
|
||||
|
||||
## Funktionen
|
||||
|
||||
- Anzahl der Tage zwischen zwei Daten
|
||||
- Anzahl der Werktage zwischen zwei Daten (mit optionaler Berücksichtigung bundeslandspezifischer Feiertage)
|
||||
- Anzeige des Wochentags eines Datums
|
||||
- Datum plus/minus X Tage
|
||||
- Datum plus/minus X Werktage
|
||||
- Datum plus/minus X Wochen/Monate
|
||||
- Kalenderwoche zu Datum
|
||||
- Start-/Enddatum einer Kalenderwoche eines Jahres
|
||||
- Integrierter Taschenrechner mit History und Sprachausgabe
|
||||
- Mehrsprachige Unterstützung (Deutsch/Englisch) mit automatischer Browser-Spracherkennung
|
||||
- Sprachausgabe für alle Ergebnisse (barrierefrei)
|
||||
- Statistik-Dashboard mit Passwortschutz unter `/stats`
|
||||
|
||||
## Bundesland-Feiertage
|
||||
|
||||
Die Werktagsberechnung kann optional bundeslandspezifische Feiertage berücksichtigen. Dazu wird die kostenlose API von [feiertage-api.de](https://feiertage-api.de) verwendet.
|
||||
|
||||
**Verfügbare Bundesländer:**
|
||||
|
||||
- Baden-Württemberg (BW)
|
||||
- Bayern (BY)
|
||||
- Berlin (BE)
|
||||
- Brandenburg (BB)
|
||||
- Bremen (HB)
|
||||
- Hamburg (HH)
|
||||
- Hessen (HE)
|
||||
- Mecklenburg-Vorpommern (MV)
|
||||
- Niedersachsen (NI)
|
||||
- Nordrhein-Westfalen (NW)
|
||||
- Rheinland-Pfalz (RP)
|
||||
- Saarland (SL)
|
||||
- Sachsen (SN)
|
||||
- Sachsen-Anhalt (ST)
|
||||
- Schleswig-Holstein (SH)
|
||||
- Thüringen (TH)
|
||||
|
||||
Die Feiertage werden automatisch für den gewählten Zeitraum abgerufen und bei der Werktagsberechnung als arbeitsfreie Tage behandelt. Im Ergebnis werden zusätzlich die Anzahl der Wochenendtage und Feiertage angezeigt.
|
||||
|
||||
## Mehrsprachige Unterstützung (i18n)
|
||||
|
||||
Die Anwendung unterstützt Deutsch und Englisch mit folgenden Features:
|
||||
|
||||
### Automatische Spracherkennung:
|
||||
|
||||
- *Browser-Sprache*: Automatische Erkennung der Browser-Einstellung
|
||||
- *URL-Parameter*: Sprachauswahl über `?lang=de` oder `?lang=en`
|
||||
- *localStorage*: Persistente Sprachauswahl im Browser
|
||||
- *Fallback*: Deutsch als Standardsprache
|
||||
|
||||
### *Datenschutzfreundliche Implementierung:*
|
||||
|
||||
- *Keine Cookies*: Sprachauswahl ohne Cookies
|
||||
- *URL-Parameter*: Transparente Sprachauswahl in der URL
|
||||
- *localStorage*: Lokale Speicherung im Browser
|
||||
- *Teilbare URLs*: URLs mit Sprachauswahl können geteilt werden
|
||||
|
||||
### *Barrierefreiheit:*
|
||||
|
||||
- *Screenreader*: Vollständige Unterstützung
|
||||
- *Tastatur-Navigation*: Vollständig bedienbar
|
||||
- *ARIA-Attribute*: Korrekte Beschriftungen
|
||||
- *Semantische HTML*: Korrekte Struktur
|
||||
- *Taschenrechner*: Vollständig barrierefrei mit Tastatur-Bedienung und Sprachausgabe
|
||||
|
||||
### *Technische Details:*
|
||||
|
||||
- *Flask-Babel*: Professionelle i18n-Implementierung
|
||||
- *Gettext*: Standard für Übersetzungen
|
||||
- *Responsive Design*: Angepasst für alle Geräte
|
||||
- *SEO-freundlich*: URLs sind indexierbar
|
||||
|
||||
## Installation (lokal)
|
||||
|
||||
1. Python 3.8+ installieren
|
||||
2. Abhängigkeiten installieren:
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
## Starten der App
|
||||
|
||||
```bash
|
||||
python app.py
|
||||
```
|
||||
|
||||
Die App ist dann unter http://localhost:5000 erreichbar.
|
||||
|
||||
## Statistik-Dashboard (/stats) & Passwortschutz
|
||||
|
||||
Das Dashboard ist mit einem statischen Passwort geschützt, das über die Umgebungsvariable `STATS_PASSWORD` gesetzt wird.
|
||||
|
||||
|
||||
|
||||
Beispiel (PowerShell):
|
||||
|
||||
```powershell
|
||||
$env:STATS_PASSWORD = "meinSicheresPasswort"
|
||||
python app.py
|
||||
```
|
||||
|
||||
Für Docker:
|
||||
|
||||
```powershell
|
||||
$env:STATS_PASSWORD = "meinSicheresPasswort"
|
||||
docker run -e STATS_PASSWORD=$env:STATS_PASSWORD -p 5000:5000 datumsrechner
|
||||
```
|
||||
|
||||
## Docker (empfohlen für Produktion)
|
||||
|
||||
Die App läuft im Container mit dem WSGI-Server **Gunicorn**:
|
||||
|
||||
```bash
|
||||
docker build -t datumsrechner .
|
||||
docker run -p 5000:5000 datumsrechner
|
||||
```
|
||||
|
||||
- Gunicorn startet automatisch (siehe Dockerfile)
|
||||
- Empfohlen für produktiven Einsatz
|
||||
|
||||
### Log-Verzeichnis mounten (Logs auf dem Host speichern)
|
||||
|
||||
Um die Logdateien außerhalb des Containers zu speichern, kannst du das log-Verzeichnis mounten:
|
||||
|
||||
**PowerShell-Beispiel:**
|
||||
|
||||
```powershell
|
||||
docker run -e STATS_PASSWORD=deinPasswort -p 5000:5000 -v ${PWD}/log:/app/log datumsrechner
|
||||
```
|
||||
|
||||
### docker-compose Beispiel
|
||||
|
||||
Erstelle eine Datei `docker-compose.yml`:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
datumsrechner:
|
||||
build: .
|
||||
ports:
|
||||
- "5000:5000"
|
||||
environment:
|
||||
- STATS_PASSWORD=deinPasswort
|
||||
volumes:
|
||||
- ./log:/app/log
|
||||
```
|
||||
|
||||
Starte mit:
|
||||
|
||||
```bash
|
||||
docker-compose up --build
|
||||
```
|
||||
|
||||
## REST API
|
||||
|
||||
Alle Datumsfunktionen stehen auch als REST-API zur Verfügung. Die API akzeptiert und liefert JSON.
|
||||
|
||||
**Basis-URL:** `http://localhost:5000/api/`
|
||||
|
||||
**Swagger Dokumentation:** [https://date.elpatron.me/api-docs](https://date.elpatron.me/api-docs)
|
||||
|
||||
**Hinweis:** Die Nutzung der REST API wird im Statistik-Dashboard ausgewertet und als Diagramm angezeigt.
|
||||
|
||||
### Endpunkte und Beispiele
|
||||
|
||||
#### 1. Tage/Werktage zwischen zwei Daten
|
||||
|
||||
**POST** `/api/tage_werktage`
|
||||
|
||||
```json
|
||||
{
|
||||
"start": "2024-06-01",
|
||||
"end": "2024-06-10",
|
||||
"werktage": true,
|
||||
"bundesland": "BY"
|
||||
}
|
||||
```
|
||||
|
||||
**Mit curl:**
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:5000/api/tage_werktage \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"start": "2024-06-01", "end": "2024-06-10", "werktage": true, "bundesland": "BY"}'
|
||||
```
|
||||
|
||||
**Antwort:**
|
||||
|
||||
```json
|
||||
{ "result": 7 }
|
||||
```
|
||||
|
||||
**Hinweis:** Der Parameter `bundesland` ist optional und wird nur bei `"werktage": true` berücksichtigt. Verfügbare Bundesland-Kürzel siehe oben.
|
||||
|
||||
#### 2. Wochentag zu einem Datum
|
||||
|
||||
**POST** `/api/wochentag`
|
||||
|
||||
```json
|
||||
{ "datum": "2024-06-10" }
|
||||
```
|
||||
|
||||
**Mit curl:**
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:5000/api/wochentag \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"datum": "2024-06-10"}'
|
||||
```
|
||||
|
||||
**Antwort:**
|
||||
|
||||
```json
|
||||
{ "result": "Montag" }
|
||||
```
|
||||
|
||||
#### 3. Kalenderwoche zu Datum
|
||||
|
||||
**POST** `/api/kw_berechnen`
|
||||
|
||||
```json
|
||||
{ "datum": "2024-06-10" }
|
||||
```
|
||||
|
||||
**Mit curl:**
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:5000/api/kw_berechnen \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"datum": "2024-06-10"}'
|
||||
```
|
||||
|
||||
**Antwort:**
|
||||
|
||||
```json
|
||||
{ "result": "KW 24 (2024)", "kw": 24, "jahr": 2024 }
|
||||
```
|
||||
|
||||
#### 4. Start-/Enddatum einer Kalenderwoche
|
||||
|
||||
**POST** `/api/kw_datum`
|
||||
|
||||
```json
|
||||
{ "jahr": 2024, "kw": 24 }
|
||||
```
|
||||
|
||||
**Mit curl:**
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:5000/api/kw_datum \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"jahr": 2024, "kw": 24}'
|
||||
```
|
||||
|
||||
**Antwort:**
|
||||
|
||||
```json
|
||||
{
|
||||
"result": "10.06.2024 bis 16.06.2024",
|
||||
"start": "2024-06-10",
|
||||
"end": "2024-06-16"
|
||||
}
|
||||
```
|
||||
|
||||
#### 5. Datum plus/minus Tage, Wochen, Monate
|
||||
|
||||
**POST** `/api/plusminus`
|
||||
|
||||
```json
|
||||
{
|
||||
"datum": "2024-06-10",
|
||||
"anzahl": 5,
|
||||
"einheit": "tage",
|
||||
"richtung": "add",
|
||||
"werktage": false
|
||||
}
|
||||
```
|
||||
|
||||
**Mit curl:**
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:5000/api/plusminus \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"datum": "2024-06-10", "anzahl": 5, "einheit": "tage", "richtung": "add", "werktage": false}'
|
||||
```
|
||||
|
||||
**Antwort:**
|
||||
|
||||
```json
|
||||
{ "result": "2024-06-15" }
|
||||
```
|
||||
|
||||
**Hinweis:**
|
||||
|
||||
- `"einheit"`: `"tage"`, `"wochen"` oder `"monate"`
|
||||
- `"richtung"`: `"add"` (plus) oder `"sub"` (minus)
|
||||
- `"werktage"`: `true` für Werktage, sonst `false` (nur bei `"tage"` unterstützt)
|
||||
|
||||
#### 6. Statistik
|
||||
|
||||
**GET** `/api/stats`
|
||||
|
||||
**Mit curl:**
|
||||
|
||||
```bash
|
||||
curl http://localhost:5000/api/stats
|
||||
```
|
||||
|
||||
**Antwort:**
|
||||
|
||||
```json
|
||||
{
|
||||
"pageviews": 42,
|
||||
"func_counts": { "plusminus": 10, "tage_werktage": 5 },
|
||||
"impressions_per_day": { "2024-06-10": 7 }
|
||||
}
|
||||
```
|
||||
|
||||
#### 7. Monitoring & Healthcheck
|
||||
|
||||
**GET** `/api/monitor`
|
||||
|
||||
**Mit curl:**
|
||||
|
||||
```bash
|
||||
curl http://localhost:5000/api/monitor
|
||||
```
|
||||
|
||||
**Antwort:**
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"message": "App running",
|
||||
"time": "2025-07-24T13:37:00.123456",
|
||||
"uptime_seconds": 12345,
|
||||
"pageviews_last_7_days": 42
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Fehlerfälle** liefern immer einen HTTP-Statuscode 400 und ein JSON mit `"error"`-Feld, z.B.:
|
||||
|
||||
```json
|
||||
{ "error": "Ungültige Eingabe", "details": "..." }
|
||||
```
|
||||
|
||||
## Progressive Web App (PWA)
|
||||
|
||||
Elpatrons Datumsrechner ist als PWA installierbar (z.B. auf Android/iOS-Homescreen oder Desktop). Die App funktioniert offline für die Startseite und statische Ressourcen, die Datumsberechnung bleibt serverseitig.
|
||||
|
||||
- Manifest und Service Worker sind integriert
|
||||
- App-Icon und Theme-Color für Homescreen
|
||||
- Installation über Browser-Menü ("Zum Startbildschirm hinzufügen")
|
||||
- Taschenrechner funktioniert vollständig clientseitig (offline verfügbar)
|
||||
|
||||
## Monitoring & Healthcheck
|
||||
|
||||
Die App bietet einen Monitoring-Endpunkt unter `/monitor`, der Statusinformationen als JSON zurückgibt (z.B. für Uptime-Robot, Docker Healthcheck oder eigene Tools):
|
||||
|
||||
- Status (ok)
|
||||
- Aktuelle Serverzeit
|
||||
- Uptime (Sekunden seit Start)
|
||||
- Pageviews der letzten 7 Tage
|
||||
|
||||
Beispiel-Aufruf:
|
||||
|
||||
`GET https://date.elpatron.me/monitor`
|
||||
|
||||
Antwort:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"message": "App running",
|
||||
"time": "2025-07-24T13:37:00.123456",
|
||||
"uptime_seconds": 12345,
|
||||
"pageviews_last_7_days": 42
|
||||
}
|
||||
```
|
||||
|
||||
## Entwicklung & Hinweise
|
||||
|
||||
- Die HTML-Templates liegen im Ordner `templates/` (Trennung von Logik und Darstellung)
|
||||
- Das Projekt ist auf Codeberg gehostet: [https://codeberg.org/elpatron/datecalc](https://codeberg.org/elpatron/datecalc)
|
||||
- Modernes, responsives Design mit Akkordeon und Icons
|
||||
|
||||
## Automatisierte Tests
|
||||
|
||||
Automatisierte Tests sind mit pytest möglich:
|
||||
|
||||
```powershell
|
||||
pip install -r requirements.txt
|
||||
pytest test_app.py
|
||||
```
|
||||
|
||||
Die Tests prüfen u.a. die Erreichbarkeit der App, die wichtigsten Funktionen und den Schutz vor XSS-Angriffen.
|
||||
|
||||
## Hinweise
|
||||
|
||||
### Motivation
|
||||
|
||||
Finde mal eine Datumsrechner- Webapp, die nicht völlig Werbe- und Tracking verseucht ist! Da ich sowas häufiger mal brauche, hab ich mir eine eigene gemacht.
|
||||
|
||||
### Vibe Coding
|
||||
|
||||
Dieses Projekt wurde zu nahezu 100% mit Unterstützung künsticher Intelligenz (*[Vibe Coding](https://de.wikipedia.org/wiki/Vibe_Coding)*) erstellt. Das Grundgerüst war nach ca. 45 Minuten fertig gestellt, insgesamt hat die Entwicklung des Projekts ca. 12 Stunden Zeit beansprucht.
|
||||
|
||||
### Statistik-Erfassung, Logging
|
||||
|
||||
Es werden keine IP-Adressen oder sonstigen persönlichen Daten gespeichert, lediglich die Zahl der Aufrufe der Funktionen in einer kumulierten Darstellung. Die Logdatei enthält nur Einträge der letzten sieben Tage.
|
||||
|
||||
### Barrierefreiheit (Accessibility)
|
||||
|
||||
*Elpatrons Datumsrechner* ist barrierefrei gestaltet und erfüllt zentrale Anforderungen an Accessibility (a11y):
|
||||
|
||||
- *Semantische HTML-Struktur:* Überschriften, Labels und Formularelemente sind korrekt ausgezeichnet und verknüpft.
|
||||
- *ARIA-Attribute:* Accordion und Statusmeldungen sind mit ARIA-Attributen versehen, damit Screenreader die Struktur und Zustände erkennen.
|
||||
- *Tastaturbedienbarkeit:* Alle interaktiven Elemente (Accordion, Buttons, Formulare) sind vollständig per Tastatur bedienbar (inkl. Fokus-Indikator und Pfeiltasten-Navigation im Accordion).
|
||||
- *Fokus-Indikatoren:* Deutliche visuelle Hervorhebung des Fokus für alle Bedienelemente.
|
||||
- *Farbkontraste:* Hohe Kontraste für Texte, Buttons und Ergebnisboxen, geprüft nach WCAG-Richtlinien.
|
||||
- *Status- und Fehlermeldungen:* Ergebnisse und Fehler werden mit `aria-live` für Screenreader zugänglich gemacht.
|
||||
- *Sprachausgabe:* Alle Ergebnisse können über 🔊-Buttons vorgelesen werden (Web Speech API, deutsche Sprache).
|
||||
- *Taschenrechner:* Vollständig barrierefrei mit Tastatur-Bedienung, Sprachausgabe und History-Funktion.
|
||||
- *Mobile Optimierung:* Zusätzliche Meta-Tags für bessere Bedienbarkeit auf mobilen Geräten und Unterstützung von Screenreadern.
|
||||
- *SEO:* Das Thema Barrierefreiheit ist in den Meta-Tags für Suchmaschinen sichtbar.
|
||||
|
||||
Damit ist die App für Menschen mit unterschiedlichen Einschränkungen (z.B. Sehbehinderung, motorische Einschränkungen) gut nutzbar und entspricht modernen Webstandards.
|
||||
|
||||
### Code Statistik
|
||||
|
||||
cloc|github.com/AlDanial/cloc v 2.06 T=0.23 s (109.5 files/s, 30735.0 lines/s)
|
||||
--- | ---
|
||||
|
||||
Language|files|blank|comment|code
|
||||
:-------|-------:|-------:|-------:|-------:
|
||||
HTML|8|159|8|2805
|
||||
Python|2|66|74|739
|
||||
JavaScript|2|95|88|580
|
||||
PO File|2|260|266|544
|
||||
Markdown|3|184|0|498
|
||||
JSON|3|0|0|243
|
||||
CSS|1|186|3|188
|
||||
SVG|2|0|0|14
|
||||
Dockerfile|1|5|6|8
|
||||
DOS Batch|1|0|0|1
|
||||
--------|--------|--------|--------|--------
|
||||
SUM:|25|955|445|5620
|
||||
|
||||
## Lizenz
|
||||
|
||||
Dieses Projekt steht unter der [MIT-Lizenz](LICENSE).
|
||||
|
||||
---
|
||||
(c) 2025 [Markus Busche](https://digitalcourage.social/@elpatron)
|
||||
|
||||
**Version 1.4.12** - Integrierter Taschenrechner mit History und Sprachausgabe hinzugefügt
|
||||
Reference in New Issue
Block a user