Problem or Motivation
OpenCloudTouch documentation is currently a mix of German and English. CONTRIBUTING.md contains German section headers (Commit-Richtlinien, Architektur, Kontakt), German body text, and German inline phrasing throughout. Parts of README.md are German. ADRs and other technical docs are inconsistent. This creates a significant barrier for international contributors and users who do not speak German.
The 10-language i18n feature (#109) has just been merged, demonstrating the project's international reach. The documentation must now match that ambition: English as the single source of truth for all technical content.
Desired Behaviour
1. README.md — Bilingual intro, English-only everywhere else
The README should be the project's front door for both German and English speakers. Structure:
# OpenCloudTouch (OCT)
<!-- German intro block (≤ 40 lines) -->
## Was ist OpenCloudTouch?
## Was kann man damit machen?
## Quickstart (DE)
<!-- English intro block (≤ 40 lines) -->
## What is OpenCloudTouch?
## What can you do with it?
## Quickstart (EN)
<!-- English-only from here -->
## Architecture
## Project Structure
## Configuration
## Troubleshooting
## Roadmap
## Contributing → link to CONTRIBUTING.md + Wiki
## Community → link to GitHub Discussions (EN) + Wiki
## License
Rules:
- Both intros must be kept in sync whenever content changes (a comment marker
<!-- SYNC: also update DE/EN block --> above each block)
- Quickstart in both languages covers: Docker Compose one-liner + link to Wiki for full setup
- Everything beyond Quickstart is English-only, with a note: "For more details see the Wiki"
2. CONTRIBUTING.md — Full English rewrite
Current state: German headers + German body text throughout.
Required sections (all English):
| Section |
Action |
| Quick Start for Contributors |
Translate to English |
| Commit Guidelines (Conventional Commits) |
Translate header + body |
| Testing (backend, frontend, e2e, UX/a11y) |
Translate |
| Development Workflow |
Translate |
| Code Style (Python/TS) |
Translate |
| Architecture (backend, frontend) |
Translate |
| Bug Reports |
Translate |
| Feature Requests |
Translate |
| Security |
Translate |
| Translations (i18n) |
Keep/extend in English |
| Documentation |
Translate |
| Pull Request Checklist |
Translate |
| Learning Resources |
Translate |
| Code Review |
Translate |
| Contact |
Translate (remove German Kontakt header) |
| License |
Translate |
No German text must remain anywhere in the file.
3. All other documentation files — English only
Files to audit and rewrite where German content exists:
| File |
Required Action |
docs/adr/006-radio-pagination.md |
Audit: translate any German sections |
docs/adr/007-i18n-architecture.md |
Audit: translate any German sections |
deployment/README.md |
Translate to English |
deployment/LOCAL-DEPLOYMENT.md |
Translate to English |
deployment/local/README.md |
Translate to English |
deployment/raspi-image/README.md |
Translate to English |
apps/backend/README.md |
Translate to English |
apps/frontend/README.md |
Translate to English |
apps/frontend/DEVELOPMENT-MODES.md |
Translate to English |
AGENTS.md |
Audit + translate any German headings/text |
CHANGELOG.md |
All future entries: English only. Existing entries: translate headings, keep content |
DISCLAIMER.md |
Translate to English (legal disclaimer) |
.github/SECURITY.md (if exists) |
English only |
4. GitHub Discussions / Q&A
- Pin an announcement in GitHub Discussions: "This project uses English as the language for all discussions, issues, and Q&A."
- Add a short note to
CONTRIBUTING.md under a Community section: discussions, issues, and PR comments must be in English
- Update any existing discussion category descriptions that contain German text
5. Wiki
The Wiki is the only place where bilingual content is maintained:
| Wiki page |
Language |
| Home |
German + English |
| Was ist OpenCloudTouch? / What is OpenCloudTouch? |
German + English |
| Installation (Raspberry Pi) |
German + English |
| All other Wiki pages (Setup, Config, Troubleshooting, FAQ) |
English only |
All other docs/READMEs should link to the appropriate Wiki page instead of duplicating content.
6. Documentation audit
As part of this issue, perform a full audit of all .md files in the repository (excluding .local/, .specify/, specs/, .pytest_cache/) and produce a checklist:
The audit result must be posted as a comment on this issue before implementation begins.
Alternatives Considered
- German + English in all docs: Doubles maintenance burden, creates drift, and confuses contributors about which version is canonical. Rejected.
- English only including README intro: The README intro section serves as the first touchpoint for German-speaking end users who may not be developers. A bilingual intro lowers the barrier without adding meaningful maintenance cost. Kept.
Additional Context
Acceptance Criteria
Problem or Motivation
OpenCloudTouch documentation is currently a mix of German and English.
CONTRIBUTING.mdcontains German section headers (Commit-Richtlinien,Architektur,Kontakt), German body text, and German inline phrasing throughout. Parts ofREADME.mdare German. ADRs and other technical docs are inconsistent. This creates a significant barrier for international contributors and users who do not speak German.The 10-language i18n feature (#109) has just been merged, demonstrating the project's international reach. The documentation must now match that ambition: English as the single source of truth for all technical content.
Desired Behaviour
1. README.md — Bilingual intro, English-only everywhere else
The README should be the project's front door for both German and English speakers. Structure:
Rules:
<!-- SYNC: also update DE/EN block -->above each block)2. CONTRIBUTING.md — Full English rewrite
Current state: German headers + German body text throughout.
Required sections (all English):
Kontaktheader)No German text must remain anywhere in the file.
3. All other documentation files — English only
Files to audit and rewrite where German content exists:
docs/adr/006-radio-pagination.mddocs/adr/007-i18n-architecture.mddeployment/README.mddeployment/LOCAL-DEPLOYMENT.mddeployment/local/README.mddeployment/raspi-image/README.mdapps/backend/README.mdapps/frontend/README.mdapps/frontend/DEVELOPMENT-MODES.mdAGENTS.mdCHANGELOG.mdDISCLAIMER.md.github/SECURITY.md(if exists)4. GitHub Discussions / Q&A
CONTRIBUTING.mdunder a Community section: discussions, issues, and PR comments must be in English5. Wiki
The Wiki is the only place where bilingual content is maintained:
All other docs/READMEs should link to the appropriate Wiki page instead of duplicating content.
6. Documentation audit
As part of this issue, perform a full audit of all
.mdfiles in the repository (excluding.local/,.specify/,specs/,.pytest_cache/) and produce a checklist:The audit result must be posted as a comment on this issue before implementation begins.
Alternatives Considered
Additional Context
CONTRIBUTING.mdalready has an English i18n section (L401) added in feat: i18n 10 languages + About section + deploy fix #114 — this is the target quality for the entire filedocs/adr/008-documentation-language.mdAcceptance Criteria
README.mdhas a German intro block AND an English intro block, both in sync, everything else EnglishCONTRIBUTING.mdcontains zero German textdocs/adr/*.mdfiles are fully Englishdeployment/**/*.mdfiles are fully Englishapps/**/README.mdandapps/**/*.mdfiles are fully EnglishCHANGELOG.mdexisting headings translated, all future entries EnglishDISCLAIMER.mdis EnglishAGENTS.mdcontains no German textCONTRIBUTING.md