ADR-012: Bilingual Documentation (English + German) mit Literal-Übersetzung

Status

Accepted

Context

Das LLM-Coding/Semantic-Anchors Repository dokumentiert seine Anchors und Konzepte konsequent zweisprachig (Englisch + Deutsch), erkennbar an der .de.adoc-Suffix-Konvention:

docs/
  about.adoc              ← Englisch
  about.de.adoc           ← Deutsch
  CONTRIBUTING.adoc       ← Englisch
  CONTRIBUTING.de.adoc    ← Deutsch
  agentskill.adoc         ← Englisch
  agentskill.de.adoc      ← Deutsch
  brownfield-workflow.adoc
  brownfield-workflow.de.adoc
  rejected-proposals.adoc
  rejected-proposals.de.adoc
  socratic-recovery-skill.adoc
  socratic-recovery-skill.de.adoc
  spec-driven-workflow.adoc
  spec-driven-workflow.de.adoc

Source Anchor: https://github.com/LLM-Coding/Semantic-Anchors/tree/main/docs — 7 von 14 Doku-Dateien haben eine .de.adoc-Parallele.

Unser Plugin wird als Contribution in dieses Repository eingebracht (Phase 5). Die Design-Dokumentation muss daher ebenfalls zweisprachig geführt werden, um: 1. Kompatibilität mit der Sprachkonvention des Upstream-Repos 2. Barrierefreiheit für deutsch- und englischsprachige Leser 3. Fachliche Präzision — Architekturkonzepte sind oft leichter in der Muttersprache erfassbar

Das Problem der Übersetzung

Technische Übersetzungen haben eine fundamentale Schwierigkeit: Viele Fachbegriffe haben keine 1:1-Entsprechung (z.B. "Steering Correctness" → "Lenkungsrichtigkeit" vs. "Steuerungskorrektheit"). Bei Mehrdeutigkeit muss die Übersetzung gewählt werden, die den Intent und die fachliche Korrektheit am besten abbildet — nicht die wörtlichste.

Alternatives Considered

Option A: Nur Englisch (Monolingual)

Die Doku wird ausschliesslich auf Englisch geführt.

Vorteile: - Single Source of Truth — keine Synchronisation nötig - Weniger Pflegeaufwand (50% weniger Dateien) - Englisch ist De-facto-Standard für technische Dokumentation - Keine Übersetzungsfehler möglich

Nachteile: - Inkompatibel mit der Sprachstrategie des Semantic-Anchors-Repos (.de.adoc-Dateien) - Deutschsprachige Stakeholder werden ausgeschlossen - arc42 ist ein deutschsprachiges Template — Kernkonzepte sind oft nur im Deutschen präzise - Widerspricht dem Target Contribution (das Repo erwartet Zweisprachigkeit)

Option B: Zweisprachig mit parallel geführten Dateien (gewählt)

Jede Doku-Datei existiert in zwei Sprachversionen: .md (Englisch) und .de.md (Deutsch). Übersetzungsprinzip: wörtlich, bei Mehrdeutigkeit entscheidet der Intent und die Fachlichkeit.

Vorteile: - 1:1-kompatibel mit dem Upstream-Repo (.de-Suffix) - Klare Trennung: Leser wählen ihre Sprache - arc42 deutsch/englisch nativ unterstützt - Übersetzungsqualität ist nachvollziehbar (Git-Diff über die parallele Datei)

Nachteile: - Doppelter Pflegeaufwand (Änderungen müssen in beide Versionen) - Synchronisationsrisiko: Eine Version kann veralten - Höhere Dateianzahl (+100% Doku-Dateien)

Option C: Nur Deutsch (Monolingual)

Die Doku wird ausschliesslich auf Deutsch geführt.

Vorteile: - Single Source of Truth - arc42 ist deutschsprachigen Ursprungs

Nachteile: - Internationale Leser ausgeschlossen — opencode-Plugin zielt auf internationale Community - Inkompatibel mit Contribution-Strategie (das Repo erwartet beide Sprachen) - Englisch ist Standard für opencode-Plugins

Evaluation Criteria

Kriterium Gewicht Beschreibung

Contribution-Kompatibilität

Hoch

Das Semantic-Anchors-Repo erwartet .de-Dokumente

Fachliche Präzision

Hoch

Übersetzung muss den Intent und die Domain korrekt abbilden

Pflegeaufwand

Mittel

Synchronisation der Sprachversionen

Lesbarkeit

Mittel

Beide Sprachgruppen müssen bedient werden

Synchronisationsrisiko

Niedrig

Abweichungen zwischen EN und DE müssen erkennbar sein

Decision

Option B: Zweisprachig mit parallel geführten Dateien wurde gewählt.

Begründung: - Contribution-Kompatibilität erzwingt .de-Dateien — kein Weg daran vorbei - Das Upstream-Repo (Semantic-Anchors) lebt Zweisprachigkeit vor — wir folgen dieser Konvention - arc42 ist von Haus aus zweisprachig konzipiert (deutsche Erfinder, englische Standard-Vorlage) - Der Mehraufwand wird durch Contribution-Readiness und Barrierefreiheit aufgewogen

Übersetzungsprinzip (Literal Translation mit Intent-Resolve)

Bei der Übersetzung gilt eine hierarchische Entscheidungsregel:

  1. Literal — Präzise, keine freien Paraphrasen. Jeder Satz wird so nah wie möglich am Original übersetzt. Keine sinngemässe "Verschönerung".

  2. Wenn ein Begriff mehrdeutig ist (z.B. "steering" → "Lenkung"/"Steuerung"/"Führung"), wird die Übersetzung gewählt, die den Intent Anchor (was soll passieren?) und die fachliche Korrektheit am besten abbildet.

  3. Fachbegriffe und Eigennamen bleiben unübersetzt. RuleEngine, tool.execute.before, Hook, Steering Contract werden nicht eingedeutscht.

  4. Jede Übersetzung muss im Git-Diff nachvollziehbar sein. Keine stillschweigenden Änderungen des Inhalts bei der Übersetzung.

Konvention: - Primäre Doku: docs/<section>-<titel>.md (Englisch) - Deutsche Fassung: docs/<section>-<titel>.de.md (parallel) - Bei Contribution: .md → .adoc, .de.md → .de.adoc

Consequences

  • Positiv: Contribution-Ready — das Plugin-Design erfüllt die Sprachkonvention des Upstream-Repos

  • Positiv: Deutschsprachige Stakeholder können die Doku in ihrer Muttersprache lesen

  • Positiv: arc42-Kernkonzepte sind im Deutschen präziser (z.B. "Building Block View" → "Bausteinsicht")

  • Negativ: Doppelter Pflegeaufwand bei Änderungen (beide Sprachversionen müssen aktualisiert werden)

  • Negativ: Höhere Dateianzahl — 12 arc42-Sektionen × 2 Sprachen = 24 Dateien + Concepts + Decisions

  • Trade-off: Langfristig mehr Wartungskosten, aber Contribution-Only-once-Konvertierung bleibt möglich

Related

  • ADR-007: Markdown für Design-Doku (Format-Wahl; Sprache ist separates Concern)

  • docs/02-architecture-constraints.md (Language Constraint)

  • docs/08-Konzepte/04-language-and-translation.md (detaillierte Übersetzungskonventionen)

Sources