diff --git a/CLAUDE.md b/CLAUDE.md index c301934..929ae17 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -181,6 +181,57 @@ Cards use `rounded-xl`, `ring-1`, `shadow-sm`. Responsive 1→2 column grids. --- +## Internationalisation (i18n) + +### Frontend App + +- **Library:** i18next + react-i18next +- **Locales:** `en`, `es`, `ca` (English, Spanish, Catalan) +- **Config:** `frontend/src/i18n/index.ts` — detects language from localStorage (`'lang'`), then browser, fallback `en` +- **Translation files:** `frontend/src/i18n/{en,es,ca}.json` (~173 keys each) +- **Key namespaces:** `common`, `nav`, `home`, `search`, `results`, `trip`, `notifications`, `configuration` +- **Language switcher:** rendered in the app footer (EN / ES / CA buttons), writes to localStorage + +### Docusaurus Website + +- **Locales:** `en` (default), `es`, `ca` — configured in `website/docusaurus.config.ts` +- **Translation files:** `website/i18n/{es,ca}/` + - `docusaurus-plugin-content-docs/current/` — full translated copies of all doc pages + - `docusaurus-plugin-content-docs/current.json` — sidebar category labels + - `docusaurus-theme-classic/{navbar,footer}.json` — navbar/footer UI strings +- Navbar includes a locale-selector dropdown + +--- + +## Documentation Website (`website/`) + +Docusaurus 3.7.0 static site, deployed to GitHub Pages at `https://JavierMonton.github.io/renfe-tracker/`. + +- **Config:** `website/docusaurus.config.ts`, sidebars in `website/sidebars.ts` +- **Docs served at:** `/` (base URL `/renfe-tracker/`, trailing slash disabled) +- **Content:** `website/docs/` + - `intro.md` (slug `/`) → `installation.md` → `configuration.md` + - `features/` category: `trip-tracking.md`, `price-range.md`, `possible-trains.md`, `notifications.md` +- **Custom CSS:** `website/src/css/custom.css` (Renfe colour palette) +- **Static assets:** `website/static/img/` (screenshots + logo) +- **Node version:** ≥18 + +--- + +## CI/CD (GitHub Actions) + +Three workflows in `.github/workflows/`: + +| File | Trigger | What it does | +|------|---------|--------------| +| `deploy-docs.yml` | Push to `main` touching `website/**` (or manual) | Runs `npm ci && npm run build` in `website/`, deploys to `gh-pages` branch via `peaceiris/actions-gh-pages` | +| `pr-tests.yml` | Pull request (open/sync/reopen) | Installs `uv`, runs `ruff check` + `pytest` against Python 3.11 backend | +| `release-docker.yml` | Push of `v*.*.*` tag | Builds multi-platform Docker image, pushes to Docker Hub as `{DOCKERHUB_USERNAME}/renfe-tracker:{tag}` and `:latest` | + +Docker Hub credentials stored as repository secrets `DOCKERHUB_USERNAME` / `DOCKERHUB_TOKEN`. + +--- + ## Current Status - Core features complete: trip tracking, price checking, price history, possible trains, email/HA/Telegram notifications, browser polling diff --git a/website/docs/features/notifications.md b/website/docs/features/notifications.md index 23347a3..13fe770 100644 --- a/website/docs/features/notifications.md +++ b/website/docs/features/notifications.md @@ -6,7 +6,7 @@ title: Notifications # Notifications -Whenever a tracked trip changes price, Renfe Tracker can notify you immediately. Three notification systems are supported, and you can configure as many as you like — all active notifications fire on every price change. +Whenever a tracked trip changes price, Renfe Tracker can notify you immediately. Four notification systems are supported, and you can configure as many as you like — all active notifications fire on every price change. ## Notification message format @@ -81,6 +81,46 @@ Once the notification lands in Home Assistant, you can attach any HA automation --- +## Telegram {#telegram} + +Sends a formatted message to a Telegram chat, group, or channel via a bot whenever a price changes. + +### Server-side setup (environment variables) + +Create a bot through [@BotFather](https://t.me/BotFather) to get a bot token, then obtain the chat ID of the target chat (your personal chat, a group, or a channel). + +```yaml +environment: + TELEGRAM_BOT_TOKEN: "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11" + TELEGRAM_CHAT_ID: "123456789" +``` + +The token and chat ID are read from environment variables only — they are never stored in the database. + +### Getting your chat ID + +- **Personal chat:** Start a conversation with your bot, then call `https://api.telegram.org/bot/getUpdates` and look for the `chat.id` field in the response. +- **Group or channel:** Add the bot to the group/channel, send a message, and use `getUpdates` as above. + +### Per-notification setup (UI) + +Go to **Notifications → Add notification → Telegram**. No additional fields are required — the bot token and chat ID come from the environment variables above. + +### Message format + +Messages are sent with Telegram's HTML parse mode and include the route, date, departure time, train identifier, and a price comparison showing the old price (strikethrough) and the new price with the difference: + +``` +Price decreased + +Madrid → Barcelona +2026-03-25 | 07:00 | AVE 02250 + +~~€45.10~~ → €39.50 (−€5.60) +``` + +--- + ## Browser notifications {#browser} Sends in-browser notifications via the Web Push API so you get alerts even when the Renfe Tracker tab is not open (as long as the browser is running). diff --git a/website/i18n/ca/docusaurus-plugin-content-docs/current/features/notifications.md b/website/i18n/ca/docusaurus-plugin-content-docs/current/features/notifications.md index 4816d14..6c01489 100644 --- a/website/i18n/ca/docusaurus-plugin-content-docs/current/features/notifications.md +++ b/website/i18n/ca/docusaurus-plugin-content-docs/current/features/notifications.md @@ -6,7 +6,7 @@ title: Notificacions # Notificacions -Quan el preu d'un viatge seguit canvia, Renfe Tracker pot notificar-te immediatament. S'admeten tres sistemes de notificació i pots configurar-ne tants com vulguis — totes les notificacions actives s'envien en cada canvi de preu. +Quan el preu d'un viatge seguit canvia, Renfe Tracker pot notificar-te immediatament. S'admeten quatre sistemes de notificació i pots configurar-ne tants com vulguis — totes les notificacions actives s'envien en cada canvi de preu. ## Format del missatge de notificació @@ -81,6 +81,46 @@ Un cop la notificació arriba a Home Assistant, pots adjuntar-hi qualsevol autom --- +## Telegram {#telegram} + +Envia un missatge formatat a un xat, grup o canal de Telegram a través d'un bot cada vegada que canvia un preu. + +### Configuració del servidor (variables d'entorn) + +Crea un bot a través de [@BotFather](https://t.me/BotFather) per obtenir el token del bot i, a continuació, obtén l'ID del xat de destí (el teu xat personal, un grup o un canal). + +```yaml +environment: + TELEGRAM_BOT_TOKEN: "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11" + TELEGRAM_CHAT_ID: "123456789" +``` + +El token i l'ID del xat es llegeixen únicament des de les variables d'entorn — mai no s'emmagatzemen a la base de dades. + +### Com obtenir el teu ID de xat + +- **Xat personal:** Inicia una conversa amb el teu bot i crida `https://api.telegram.org/bot/getUpdates`. Busca el camp `chat.id` a la resposta. +- **Grup o canal:** Afegeix el bot al grup o canal, envia un missatge i usa `getUpdates` com s'indica més amunt. + +### Configuració per notificació (interfície) + +Ves a **Notificacions → Afegir notificació → Telegram**. No cal cap camp addicional — el token del bot i l'ID del xat provenen de les variables d'entorn anteriors. + +### Format del missatge + +Els missatges s'envien amb el mode d'anàlisi HTML de Telegram i inclouen la ruta, la data, l'hora de sortida, l'identificador del tren i una comparació de preus amb el preu anterior (ratllat) i el nou preu amb la diferència: + +``` +Preu baixat + +Madrid → Barcelona +2026-03-25 | 07:00 | AVE 02250 + +~~€45.10~~ → €39.50 (−€5.60) +``` + +--- + ## Notificacions del navegador {#browser} Envia notificacions al navegador a través de l'API Web Push per rebre alertes fins i tot quan la pestanya de Renfe Tracker no està oberta (sempre que el navegador estigui en execució). diff --git a/website/i18n/es/docusaurus-plugin-content-docs/current/features/notifications.md b/website/i18n/es/docusaurus-plugin-content-docs/current/features/notifications.md index 8d34024..5c291f6 100644 --- a/website/i18n/es/docusaurus-plugin-content-docs/current/features/notifications.md +++ b/website/i18n/es/docusaurus-plugin-content-docs/current/features/notifications.md @@ -6,7 +6,7 @@ title: Notificaciones # Notificaciones -Cuando el precio de un viaje seguido cambia, Renfe Tracker puede notificarte de inmediato. Se admiten tres sistemas de notificación y puedes configurar tantos como quieras — todas las notificaciones activas se disparan en cada cambio de precio. +Cuando el precio de un viaje seguido cambia, Renfe Tracker puede notificarte de inmediato. Se admiten cuatro sistemas de notificación y puedes configurar tantos como quieras — todas las notificaciones activas se disparan en cada cambio de precio. ## Formato del mensaje de notificación @@ -81,6 +81,46 @@ Una vez que la notificación llega a Home Assistant, puedes adjuntarle cualquier --- +## Telegram {#telegram} + +Envía un mensaje formateado a un chat, grupo o canal de Telegram a través de un bot cada vez que cambia un precio. + +### Configuración del servidor (variables de entorno) + +Crea un bot a través de [@BotFather](https://t.me/BotFather) para obtener el token del bot y, a continuación, obtén el ID del chat de destino (tu chat personal, un grupo o un canal). + +```yaml +environment: + TELEGRAM_BOT_TOKEN: "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11" + TELEGRAM_CHAT_ID: "123456789" +``` + +El token y el ID del chat se leen únicamente desde las variables de entorno — nunca se almacenan en la base de datos. + +### Cómo obtener tu ID de chat + +- **Chat personal:** Inicia una conversación con tu bot y luego llama a `https://api.telegram.org/bot/getUpdates`. Busca el campo `chat.id` en la respuesta. +- **Grupo o canal:** Añade el bot al grupo o canal, envía un mensaje y usa `getUpdates` como se indica arriba. + +### Configuración por notificación (interfaz) + +Ve a **Notificaciones → Añadir notificación → Telegram**. No se requieren campos adicionales — el token del bot y el ID del chat provienen de las variables de entorno anteriores. + +### Formato del mensaje + +Los mensajes se envían con el modo de análisis HTML de Telegram e incluyen la ruta, la fecha, la hora de salida, el identificador del tren y una comparación de precios con el precio anterior (tachado) y el nuevo precio con la diferencia: + +``` +Precio bajado + +Madrid → Barcelona +2026-03-25 | 07:00 | AVE 02250 + +~~€45.10~~ → €39.50 (−€5.60) +``` + +--- + ## Notificaciones del navegador {#browser} Envía notificaciones en el navegador a través de la API Web Push para recibir alertas incluso cuando la pestaña de Renfe Tracker no está abierta (siempre que el navegador esté en ejecución).