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_en.md
Normal file
511
README_en.md
Normal file
@@ -0,0 +1,511 @@
|
||||
# Elpatron's Date Calculator
|
||||
|
||||
[](https://github.com/elpatron/datecalc)
|
||||
[](https://date.elpatron.me)
|
||||
[](https://date.elpatron.me)
|
||||
[](https://date.elpatron.me)
|
||||
[](https://date.elpatron.me)
|
||||
|
||||
This modern Python web application (Flask) enables various date calculations through a clear, accessible web interface.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Demo](#demo)
|
||||
- [Features](#features)
|
||||
- [Installation (local)](#installation-local)
|
||||
- [Starting the App](#starting-the-app)
|
||||
- [Statistics Dashboard & Password Protection](#statistics-dashboard--password-protection)
|
||||
- [Docker (recommended for production)](#docker-recommended-for-production)
|
||||
- [Mounting log directory](#mounting-log-directory-logs-stored-on-host)
|
||||
- [docker-compose example](#docker-compose-example)
|
||||
- [REST API](#rest-api)
|
||||
- [Days/Working days between two dates](#1-daysworking-days-between-two-dates)
|
||||
- [Weekday for a date](#2-weekday-for-a-date)
|
||||
- [Calendar week for date](#3-calendar-week-for-date)
|
||||
- [Start/End date of a calendar week](#4-startend-date-of-a-calendar-week)
|
||||
- [Date plus/minus days, weeks, months](#5-date-plusminus-days-weeks-months)
|
||||
- [Statistics](#6-statistics)
|
||||
- [Monitoring & Healthcheck](#7-monitoring--healthcheck)
|
||||
- [Progressive Web App (PWA)](#progressive-web-app-pwa)
|
||||
- [Monitoring & Healthcheck](#monitoring--healthcheck)
|
||||
- [Development & Notes](#development--notes)
|
||||
- [Automated Tests](#automated-tests)
|
||||
- [Notes](#notes)
|
||||
- [Motivation](#motivation)
|
||||
- [Vibe Coding](#vibe-coding)
|
||||
- [Statistics collection, Logging](#statistics-collection-logging)
|
||||
- [Accessibility](#accessibility)
|
||||
- [Code Statistics](#code-statistics)
|
||||
- [License](#license)
|
||||
|
||||
## Demo
|
||||
|
||||
Date Calculator Live: [https://date.elpatron.me](https://date.elpatron.me)
|
||||
|
||||
[](https://date.elpatron.me)
|
||||
|
||||
**[Lighthouse](https://en.wikipedia.org/wiki/Lighthouse_(software)) Performance Score:**
|
||||
|
||||
The web application achieves excellent performance values in all categories (Performance, Accessibility, Best Practices, SEO).
|
||||
|
||||
[Lighthouse Result (PDF)](./lighthouse/lighthouse-score.pdf)
|
||||
|
||||
## Features
|
||||
|
||||
- Number of days between two dates
|
||||
- Number of working days between two dates (with optional consideration of state-specific holidays)
|
||||
- Display of the weekday of a date
|
||||
- Date plus/minus X days
|
||||
- Date plus/minus X working days
|
||||
- Date plus/minus X weeks/months
|
||||
- Calendar week for date
|
||||
- Start/End date of a calendar week of a year
|
||||
- Integrated calculator with history and speech output
|
||||
- Multilingual support (German/English) with automatic browser language detection
|
||||
- Speech output for all results (accessible)
|
||||
- Statistics dashboard with password protection under `/stats`
|
||||
|
||||
## State Holidays
|
||||
|
||||
The working day calculation can optionally consider state-specific holidays. The free API from [feiertage-api.de](https://feiertage-api.de) is used for this purpose.
|
||||
|
||||
**Available States:**
|
||||
|
||||
- Baden-Württemberg (BW)
|
||||
- Bavaria (BY)
|
||||
- Berlin (BE)
|
||||
- Brandenburg (BB)
|
||||
- Bremen (HB)
|
||||
- Hamburg (HH)
|
||||
- Hesse (HE)
|
||||
- Mecklenburg-Vorpommern (MV)
|
||||
- Lower Saxony (NI)
|
||||
- North Rhine-Westphalia (NW)
|
||||
- Rhineland-Palatinate (RP)
|
||||
- Saarland (SL)
|
||||
- Saxony (SN)
|
||||
- Saxony-Anhalt (ST)
|
||||
- Schleswig-Holstein (SH)
|
||||
- Thuringia (TH)
|
||||
|
||||
Holidays are automatically retrieved for the selected time period and treated as non-working days in the working day calculation. The result also shows the number of weekend days and holidays.
|
||||
|
||||
## Multilingual Support (i18n)
|
||||
|
||||
The application supports German and English with the following features:
|
||||
|
||||
### Automatic Language Detection:
|
||||
|
||||
- *Browser Language*: Automatic detection of browser settings
|
||||
- *URL Parameter*: Language selection via `?lang=de` or `?lang=en`
|
||||
- *localStorage*: Persistent language selection in browser
|
||||
- *Fallback*: German as default language
|
||||
|
||||
### *Privacy-friendly Implementation:*
|
||||
|
||||
- *No Cookies*: Language selection without cookies
|
||||
- *URL Parameters*: Transparent language selection in URL
|
||||
- *localStorage*: Local storage in browser
|
||||
- *Shareable URLs*: URLs with language selection can be shared
|
||||
|
||||
### *Accessibility:*
|
||||
|
||||
- *Screen Reader*: Full support
|
||||
- *Keyboard Navigation*: Fully operable
|
||||
- *ARIA Attributes*: Correct labels
|
||||
- *Semantic HTML*: Correct structure
|
||||
- *Calculator*: Fully accessible with keyboard operation and speech output
|
||||
|
||||
### *Technical Details:*
|
||||
|
||||
- *Flask-Babel*: Professional i18n implementation
|
||||
- *Gettext*: Standard for translations
|
||||
- *Responsive Design*: Adapted for all devices
|
||||
- *SEO-friendly*: URLs are indexable
|
||||
|
||||
## Installation (local)
|
||||
|
||||
1. Install Python 3.8+
|
||||
2. Install dependencies:
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
## Starting the App
|
||||
|
||||
```bash
|
||||
python app.py
|
||||
```
|
||||
|
||||
The app is then accessible at http://localhost:5000.
|
||||
|
||||
## Statistics Dashboard (/stats) & Password Protection
|
||||
|
||||
The dashboard is protected with a static password that is set via the environment variable `STATS_PASSWORD`.
|
||||
|
||||
|
||||
|
||||
Example (PowerShell):
|
||||
|
||||
```powershell
|
||||
$env:STATS_PASSWORD = "mySecurePassword"
|
||||
python app.py
|
||||
```
|
||||
|
||||
For Docker:
|
||||
|
||||
```powershell
|
||||
$env:STATS_PASSWORD = "mySecurePassword"
|
||||
docker run -e STATS_PASSWORD=$env:STATS_PASSWORD -p 5000:5000 datumsrechner
|
||||
```
|
||||
|
||||
## Docker (recommended for production)
|
||||
|
||||
The app runs in a container with the **Gunicorn** WSGI server:
|
||||
|
||||
```bash
|
||||
docker build -t datumsrechner .
|
||||
docker run -p 5000:5000 datumsrechner
|
||||
```
|
||||
|
||||
- Gunicorn starts automatically (see Dockerfile)
|
||||
- Recommended for production use
|
||||
|
||||
### Mounting log directory (Logs stored on host)
|
||||
|
||||
To store log files outside the container, you can mount the log directory:
|
||||
|
||||
**PowerShell Example:**
|
||||
|
||||
```powershell
|
||||
docker run -e STATS_PASSWORD=yourPassword -p 5000:5000 -v ${PWD}/log:/app/log datumsrechner
|
||||
```
|
||||
|
||||
### docker-compose example
|
||||
|
||||
Create a `docker-compose.yml` file:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
datumsrechner:
|
||||
build: .
|
||||
ports:
|
||||
- "5000:5000"
|
||||
environment:
|
||||
- STATS_PASSWORD=yourPassword
|
||||
volumes:
|
||||
- ./log:/app/log
|
||||
```
|
||||
|
||||
Start with:
|
||||
|
||||
```bash
|
||||
docker-compose up --build
|
||||
```
|
||||
|
||||
## REST API
|
||||
|
||||
All date functions are also available as a REST API. The API accepts and returns JSON.
|
||||
|
||||
**Base URL:** `http://localhost:5000/api/`
|
||||
|
||||
**Swagger Documentation:** [https://date.elpatron.me/api-docs](https://date.elpatron.me/api-docs)
|
||||
|
||||
**Note:** The use of the REST API is evaluated in the statistics dashboard and displayed as a chart.
|
||||
|
||||
### Endpoints and Examples
|
||||
|
||||
#### 1. Days/Working days between two dates
|
||||
|
||||
**POST** `/api/tage_werktage`
|
||||
|
||||
```json
|
||||
{
|
||||
"start": "2024-06-01",
|
||||
"end": "2024-06-10",
|
||||
"werktage": true,
|
||||
"bundesland": "BY"
|
||||
}
|
||||
```
|
||||
|
||||
**With 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"}'
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{ "result": 7 }
|
||||
```
|
||||
|
||||
**Note:** The `bundesland` parameter is optional and is only considered when `"werktage": true`. Available state abbreviations see above.
|
||||
|
||||
#### 2. Weekday for a date
|
||||
|
||||
**POST** `/api/wochentag`
|
||||
|
||||
```json
|
||||
{ "datum": "2024-06-10" }
|
||||
```
|
||||
|
||||
**With curl:**
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:5000/api/wochentag \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"datum": "2024-06-10"}'
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{ "result": "Monday" }
|
||||
```
|
||||
|
||||
#### 3. Calendar week for date
|
||||
|
||||
**POST** `/api/kw_berechnen`
|
||||
|
||||
```json
|
||||
{ "datum": "2024-06-10" }
|
||||
```
|
||||
|
||||
**With curl:**
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:5000/api/kw_berechnen \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"datum": "2024-06-10"}'
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{ "result": "CW 24 (2024)", "kw": 24, "jahr": 2024 }
|
||||
```
|
||||
|
||||
#### 4. Start/End date of a calendar week
|
||||
|
||||
**POST** `/api/kw_datum`
|
||||
|
||||
```json
|
||||
{ "jahr": 2024, "kw": 24 }
|
||||
```
|
||||
|
||||
**With curl:**
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:5000/api/kw_datum \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"jahr": 2024, "kw": 24}'
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"result": "10.06.2024 to 16.06.2024",
|
||||
"start": "2024-06-10",
|
||||
"end": "2024-06-16"
|
||||
}
|
||||
```
|
||||
|
||||
#### 5. Date plus/minus days, weeks, months
|
||||
|
||||
**POST** `/api/plusminus`
|
||||
|
||||
```json
|
||||
{
|
||||
"datum": "2024-06-10",
|
||||
"anzahl": 5,
|
||||
"einheit": "tage",
|
||||
"richtung": "add",
|
||||
"werktage": false
|
||||
}
|
||||
```
|
||||
|
||||
**With 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}'
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{ "result": "2024-06-15" }
|
||||
```
|
||||
|
||||
**Note:**
|
||||
|
||||
- `"einheit"`: `"tage"`, `"wochen"` or `"monate"`
|
||||
- `"richtung"`: `"add"` (plus) or `"sub"` (minus)
|
||||
- `"werktage"`: `true` for working days, otherwise `false` (only supported for `"tage"`)
|
||||
|
||||
#### 6. Statistics
|
||||
|
||||
**GET** `/api/stats`
|
||||
|
||||
**With curl:**
|
||||
|
||||
```bash
|
||||
curl http://localhost:5000/api/stats
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"pageviews": 42,
|
||||
"func_counts": { "plusminus": 10, "tage_werktage": 5 },
|
||||
"impressions_per_day": { "2024-06-10": 7 }
|
||||
}
|
||||
```
|
||||
|
||||
#### 7. Monitoring & Healthcheck
|
||||
|
||||
**GET** `/api/monitor`
|
||||
|
||||
**With curl:**
|
||||
|
||||
```bash
|
||||
curl http://localhost:5000/api/monitor
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"message": "App running",
|
||||
"time": "2025-07-24T13:37:00.123456",
|
||||
"uptime_seconds": 12345,
|
||||
"pageviews_last_7_days": 42
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Error cases** always return an HTTP status code 400 and JSON with an `"error"` field, e.g.:
|
||||
|
||||
```json
|
||||
{ "error": "Invalid input", "details": "..." }
|
||||
```
|
||||
|
||||
## Progressive Web App (PWA)
|
||||
|
||||
Elpatron's Date Calculator is installable as a PWA (e.g., on Android/iOS home screen or desktop). The app works offline for the homepage and static resources, date calculation remains server-side.
|
||||
|
||||
- Manifest and Service Worker are integrated
|
||||
- App icon and theme color for home screen
|
||||
- Installation via browser menu ("Add to home screen")
|
||||
- Calculator works completely client-side (available offline)
|
||||
|
||||
## Monitoring & Healthcheck
|
||||
|
||||
The app provides a monitoring endpoint at `/monitor` that returns status information as JSON (e.g., for Uptime Robot, Docker Healthcheck or own tools):
|
||||
|
||||
- Status (ok)
|
||||
- Current server time
|
||||
- Uptime (seconds since start)
|
||||
- Pageviews of the last 7 days
|
||||
|
||||
Example call:
|
||||
|
||||
`GET https://date.elpatron.me/monitor`
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"message": "App running",
|
||||
"time": "2025-07-24T13:37:00.123456",
|
||||
"uptime_seconds": 12345,
|
||||
"pageviews_last_7_days": 42
|
||||
}
|
||||
```
|
||||
|
||||
## Development & Notes
|
||||
|
||||
- HTML templates are in the `templates/` folder (separation of logic and presentation)
|
||||
- The project is hosted on Codeberg: [https://codeberg.org/elpatron/datecalc](https://codeberg.org/elpatron/datecalc)
|
||||
- Modern, responsive design with accordion and icons
|
||||
|
||||
## Automated Tests
|
||||
|
||||
Automated tests are possible with pytest:
|
||||
|
||||
```powershell
|
||||
pip install -r requirements.txt
|
||||
pytest test_app.py
|
||||
```
|
||||
|
||||
The tests check, among other things, the accessibility of the app, the most important functions, and protection against XSS attacks.
|
||||
|
||||
## Notes
|
||||
|
||||
### Motivation
|
||||
|
||||
Try to find a date calculator web app that isn't completely riddled with ads and tracking! Since I need something like this more often, I made my own.
|
||||
|
||||
### Vibe Coding
|
||||
|
||||
This project was created almost 100% with the support of artificial intelligence (*[Vibe Coding](https://en.wikipedia.org/wiki/Vibe_Coding)*). The basic framework was completed after about 45 minutes, and the total development of the project took about 12 hours.
|
||||
|
||||
### Statistics collection, Logging
|
||||
|
||||
No IP addresses or other personal data are stored, only the number of function calls in a cumulative representation. The log file only contains entries from the last seven days.
|
||||
|
||||
### Accessibility
|
||||
|
||||
*Elpatron's Date Calculator* is designed to be accessible and meets central accessibility (a11y) requirements:
|
||||
|
||||
- *Semantic HTML Structure:* Headings, labels, and form elements are correctly marked and linked.
|
||||
- *ARIA Attributes:* Accordion and status messages are equipped with ARIA attributes so that screen readers can recognize the structure and states.
|
||||
- *Keyboard Operability:* All interactive elements (accordion, buttons, forms) are fully operable by keyboard (including focus indicator and arrow key navigation in accordion).
|
||||
- *Focus Indicators:* Clear visual highlighting of focus for all control elements.
|
||||
- *Color Contrasts:* High contrasts for texts, buttons, and result boxes, tested according to WCAG guidelines.
|
||||
- *Status and Error Messages:* Results and errors are made accessible to screen readers with `aria-live`.
|
||||
- *Speech Output:* All results can be read aloud via 🔊 buttons (Web Speech API, German language).
|
||||
- *Calculator:* Fully accessible with keyboard operation, speech output, and history function.
|
||||
- *Mobile Optimization:* Additional meta tags for better usability on mobile devices and support for screen readers.
|
||||
- *SEO:* The accessibility topic is visible in meta tags for search engines.
|
||||
|
||||
This makes the app well usable for people with different disabilities (e.g., visual impairment, motor limitations) and meets modern web standards.
|
||||
|
||||
### Code Statistics
|
||||
|
||||
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
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the [MIT License](LICENSE).
|
||||
|
||||
---
|
||||
(c) 2025 [Markus Busche](https://digitalcourage.social/@elpatron)
|
||||
|
||||
**Version 1.4.12** - Integrated calculator with history and speech output added
|
||||
Reference in New Issue
Block a user