Skip to content

[Feature]: docs: migrate all documentation to English #115

@scheilch

Description

@scheilch

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:

  • Files that are already English ✅
  • Files that need translation 🔄
  • Files that are stale/outdated and should be removed ❌
  • Files that are missing and should be added ➕

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

  • README.md has a German intro block AND an English intro block, both in sync, everything else English
  • CONTRIBUTING.md contains zero German text
  • All docs/adr/*.md files are fully English
  • All deployment/**/*.md files are fully English
  • All apps/**/README.md and apps/**/*.md files are fully English
  • CHANGELOG.md existing headings translated, all future entries English
  • DISCLAIMER.md is English
  • AGENTS.md contains no German text
  • A documentation audit checklist is posted as a comment before implementation
  • GitHub Discussions: English-only policy note added to CONTRIBUTING.md
  • Wiki: Home + 2 intro pages bilingual, all others English-only
  • ADR 008 created if this decision warrants documentation
  • All CI checks pass after changes

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions