Skip to content

Commit add1dd9

Browse files
MoritzWeber0lenderom
MoritzWeber0
and
lenderom
authored
feat: Add instructions for AI agents (#393)
Add an [`AGENTS.md`](https://agents.md/) file for instructions for AI agents. The file is understood by Github Copilot, Claude Code, and other agents. In addition, add "translate" and "check" commands for pages using the Opencode framework. OpenCode is open source and can be used with different providers and models (OpenAI, Github Copilot, Anthropic). Instructions how to use the custom commands are available here: https://github.com/fipguide/fipguide.github.io/blob/feat/opencode/CONTRIBUTING.md#use-ai-for-translation-and-quality-checks It's not perfect yet - but we can improve the prompts and glossary over time. Resolves #161 --------- Signed-off-by: lennartrommeiss <61516567+lenderom@users.noreply.github.com> Co-authored-by: lennartrommeiss <61516567+lenderom@users.noreply.github.com>
1 parent fc0c0e6 commit add1dd9

File tree

11 files changed

+138
-10
lines changed

11 files changed

+138
-10
lines changed

‎.opencode/command/check.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
description: Check a page for common mistakes
3+
agent: plan
4+
---
5+
6+
Check the page $ARGUMENTS for errors. When no language is provided, check all languages of the page. Common errors are:
7+
8+
- Grammatical, typographical, or spelling errors
9+
- Not following the common terms in defined in the glossary of `AGENTS.md`
10+
- Content differs between the different languages. The content should always be the same.
11+
- The page structure doesn't follow the archetype defined in `archetypes`
12+
- Anchors of internal links are not matching the referenced and translated title
13+
- Keywords are not translated as defined in the translations table in `AGENTS.md`

‎.opencode/command/translate.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
description: Translate a page
3+
agent: build
4+
---
5+
6+
Translate the page $ARGUMENTS into the other languages.
7+
If the page already exists, only translate the added or changed parts. If the page doesn't exist, create it.
8+
9+
Follow these rules:
10+
11+
- Do not modify the meaning of content. Translate as 1:1 where possible.
12+
- Use names of the translation language for cities (e.g., Köln in German, "Cologne" in English and "eau de Cologne" in French).
13+
- Enforce the glossary and translations as defined in `AGENTS.md`.
14+
- Do not translate the keys of the front matter section, the keys of shortcodes or partials.
15+
- Use the corresponding archetype (defined in `archetypes`) as base for the translated page.
16+
- Update anchors of internal links to the corresponding section in the target language.

‎AGENTS.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# FIP Guide Guidelines
2+
3+
## Content Guidelines
4+
5+
- Content MUST support all three languages (en, de, fr)
6+
- NEVER change the meaning of content when translating. Always translate as 1:1.
7+
- ALWAYS align the content with the corresponding base (defined in `archetypes`)
8+
- ALWAYS use the exact translations for headlines (defined in `archetypes`)
9+
- ALWAYS create new content pages with `hugo new {base}/{name}` where base can be `country`, `operator` or `booking`.
10+
11+
### Glossary
12+
13+
- Use "Freifahrtschein" instead of "Freifahrtsschein"
14+
- Use "FIP Coupon" instead of "FIP free travel"
15+
- Use "Motorail train" instead of "car train"
16+
- Use "Break of journey" instead of "Journey Interruption"
17+
18+
### Translations
19+
20+
| Deutsch | Englisch | Französisch |
21+
| ------------------- | --------------- | ---------------- |
22+
| FIP Freifahrtschein | FIP Coupon | Coupon FIP |
23+
| FIP Globalpreis | FIP Global Fare | Tarif Global FIP |
24+
| FIP 50 Ticket | FIP 50 Ticket | Billet FIP 50 |
25+
26+
## Development Guidelines
27+
28+
### Build/Test Commands
29+
30+
- `hugo serve`: Start local development server
31+
- `hugo --gc --minify`: Build for production
32+
- `npx prettier --write .`: Format code
33+
- `npx pagefind --site public`: Generate search index
34+
- `pre-commit run --all-files`: Run all pre-commit checks
35+
36+
### Code Style & Conventions
37+
38+
- **HTML Templates**: Use Hugo / Go template syntax
39+
- **JavaScript**: ES6 modules with relative imports (`./filename.js`).
40+
- **CSS/SCSS**: Use SCSS with BEM-like naming, variables defined in `_variables.scss`
41+
- **Markdown**: Frontmatter in YAML format, use shortcodes for complex layouts
42+
- **i18n**: Files in `i18n/` sorted alphabetically by key, support en/de/fr languages
43+
44+
### File Structure
45+
46+
- Content in `content/` with multilingual structure (`index.en.md`, `index.de.md`, `index.fr.md`)
47+
- Layouts in `layouts/` following Hugo conventions:
48+
- Partials for reusable components in HTML files in `layouts/partials/`
49+
- Shortcodes for reusable components in Markdown files in `layouts/shortcodes/`
50+
- Assets in `assets/` (processed) and `static/` (copied as-is)
51+
52+
## Quality Standards
53+
54+
- All commits MUST pass the pre-commit hooks defined in `.pre-commit-config.yaml`
55+
- HTML templates must be valid Go template syntax
56+
- Do NOT add any comments to the code
57+
- NEVER create markdown files outside the content directory

‎CONTRIBUTING.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,8 @@ Now, enable `pre-commit` to run the check every time you want to commit changes:
6565
pre-commit install
6666
```
6767

68+
## Content Contributions
69+
6870
### Add new pages
6971

7072
To add a new country:
@@ -84,3 +86,21 @@ To add a new booking platform:
8486
```zsh
8587
hugo new booking/${PLATFORM} # Replace ${PLATFORM} with the name of the booking platform
8688
```
89+
90+
### Use AI for translation and quality checks
91+
92+
We provide commands to automatically translate and check pages. To define the commands, we use the [OpenCode AI framework](https://opencode.ai/). It's open source and can be used with different providers, models (OpenAI, Github Copilot, Anthropic), and [IDEs](https://opencode.ai/docs/ide/#installation).
93+
94+
#### Installation
95+
96+
1. Install OpenCode: https://opencode.ai/docs#install.
97+
2. Run `opencode auth login` in a terminal, select the provider and log in.
98+
3. Open the OpenCode CLI with `opencode` in a terminal.
99+
4. Run `/models` to select the model you want to use.
100+
101+
Inside the OpenCode Terminal, you can ask any question, similarly to Github Copilot or Claude Chat. In addition, we provide helpful commands:
102+
103+
- `/translate {page}`: Update the translations and add missing translations of the page. `{page}` can be the name of an operator, a country, a booking plattform, or a path to a file.
104+
- `/check {page}`: Check the page for common mistakes and report them. `{page}` can be the name of an operator, a country, a booking plattform, or a path to a file.
105+
106+
That's the recommended way. However, you can still use other frontend ends like GitHub Copilot Chat and Claude Code. We provide an [`AGENTS.md`](https://agents.md/) file for these providers in the repository, but the custom commands are not available without OpenCode.

‎archetypes/operator/index.de.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,10 @@ operator: "{{ .File.ContentBaseName }}"
3030

3131
## Gültigkeit FIP Tickets
3232

33+
<!--
34+
Die Ticketkategorien können je nach Betreiber abweichen.
35+
-->
36+
3337
FIP Freifahrtschein: <✅/⛔> \
3438
FIP Freifahrt Angehörige: <✅/⛔> \
3539
FIP 50 Tickets: <✅/⛔> \

‎archetypes/operator/index.en.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,10 @@ operator: "{{ .File.ContentBaseName }}"
3030

3131
## Validity of FIP Tickets
3232

33+
<!--
34+
The ticket categories may vary depending on the operator.
35+
-->
36+
3337
FIP Coupon: <✅/⛔> \
3438
FIP Coupon for relatives: <✅/⛔> \
3539
FIP 50 Tickets: <✅/⛔> \

‎archetypes/operator/index.fr.md‎

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,9 @@ title: "{{ .File.ContentBaseName | upper }}"
44
description: "" # Complète une description pour la compagnie ferroviaire
55
country:
66
# Ajoutez les abréviations des pays dans lesquels la compagnie ferroviaire opère en anglais.
7-
- "pays1"
8-
- "pays2"
9-
- "pays3"
7+
- "country1"
8+
- "country2"
9+
- "country3"
1010
operator: "{{ .File.ContentBaseName }}"
1111
---
1212

@@ -30,6 +30,10 @@ operator: "{{ .File.ContentBaseName }}"
3030

3131
## Validité des Billets FIP
3232

33+
<!--
34+
Les catégories de billets peuvent varier selon l'opérateur.
35+
-->
36+
3337
Coupon FIP : <✅/⛔> \
3438
Coupon FIP accompagnant : <✅/⛔> \
3539
Billets FIP 50 : <✅/⛔> \
@@ -76,6 +80,16 @@ Tarif Global FIP : <✅/⛔>
7680

7781
## Catégories de classes
7882

83+
<!--
84+
Si les catégories de classes incluent des classes supplémentaires/différentes au-delà de la 1ère et 2ème classe, elles peuvent être décrites ici. Sinon, cette section peut être supprimée.
85+
-->
86+
87+
<!--
88+
**Standard** : Comparable à la 2ème classe. \
89+
**Plus** : 1ère classe sans restauration. Un pass FIP pour la 1ère classe est requis. \
90+
**Premium** : 1ère classe avec restauration. Non réservable avec FIP.
91+
-->
92+
7993
## Achat de billets et réservations
8094

8195
### En ligne

‎content/operator/ns/index.en.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,7 @@ Trains of the Sneltrein / Regional-Express `RE` category, including the connecti
110110
### Online
111111

112112
{{% booking id="db-website"
113-
subtitle="For national and cross-border connections"
113+
subtitle="For cross-border ICE and IC connections"
114114
/%}}
115115

116116
{{% booking id="db-website-fip-db"

‎content/operator/ns/index.fr.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,7 @@ Les trains de la catégorie Sneltrein / Regional-Express `RE`, notamment les lia
110110
### En ligne
111111

112112
{{% booking id="db-website"
113-
subtitle="Pour les trajets nationaux et internationaux"
113+
subtitle="Pour les connexions ICE et IC transfrontalières"
114114
/%}}
115115

116116
{{% booking id="db-website-fip-db"

‎content/operator/oebb/index.de.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ Die ÖBB (Österreichische Bundesbahnen) ist die nationale Eisenbahngesellschaft
1919
- Aufpassen bei Zügen anderer Betreiber ohne FIP Akzeptanz
2020
- Kein FIP im Wiener Flughafenexpress `CAT`
2121
- Besondere Regeln in Zügen nach Italien, Nightjets, Autozügen und IC Bussen
22-
- FIP Freifahrt der ÖBB gilt auch in Lichtenstein
22+
- FIP Freifahrt der ÖBB gilt auch in Liechtenstein
2323

2424
## Gültigkeit FIP Tickets
2525

@@ -208,9 +208,9 @@ FIP Freifahrtscheine der ÖBB, **jedoch nicht der FS**, gelten im italienischen
208208

209209
Auf der Linie REX63 werden zwischen Pamhagen und Neusiedl am See werden sowohl FIP Fahrkarten der ÖBB als auch der GySEV anerkannt.
210210

211-
### Lichtenstein
211+
### Liechtenstein
212212

213-
Die Eisenbahn in Lichtenstein wird von der ÖBB betrieben. FIP Fahrkarten sind hier zu den österreichischen Konditionen und ohne Aufpreis gültig (Feldkirchen-Buchs SG).
213+
Die Eisenbahn in Liechtenstein wird von der ÖBB betrieben. FIP Fahrkarten sind hier zu den österreichischen Konditionen und ohne Aufpreis gültig (Feldkirchen-Buchs SG).
214214

215215
### Wien Flughafen: City Airport Train (CAT)
216216

@@ -226,7 +226,7 @@ Wer mit regulären Wiener Öffi-Tickets (z. B. Einzelfahrten oder 24/48/72-Stund
226226

227227
### Schneebergbahn
228228

229-
Die Schneebergbahn ist zwar kein Teil der ÖBB oder FIP gewähnt jedoch bei Vorlage des FIP Ausweises 50% Rabatt auf Tickets.
229+
Die Schneebergbahn ist zwar kein Teil der ÖBB oder FIP gewährt jedoch bei Vorlage des FIP Ausweises 50% Rabatt auf Tickets.
230230

231231
### ÖBB Postbus
232232

0 commit comments

Comments
 (0)