# Konzept: Mehrsprachige Dokumentation (DE/EN)

**Status:** Konzept
**Datum:** 2025-01-07
**Priorität:** DE/EN
**Anforderung:** Docstrings müssen übersetzt werden (IDE-Integration für Entwickler)

## Problemstellung

Aktuelle Dokumentation (Markdown + Docstrings) ist vollständig auf Deutsch. Englischsprachige Entwickler benötigen übersetzte Docstrings in ihrer IDE, nicht nur externe Dokumentation.

## Bewertungskriterien

- **Wartungsaufwand:** Laufender Aufwand für Synchronisation
- **IDE-Integration:** Docstrings in beiden Sprachen verfügbar
- **Technische Komplexität:** Implementierungsaufwand
- **Tooling:** Automatisierungsmöglichkeiten

## Option 1: Bilinguale Docstrings im Code

### Konzept

Docstrings enthalten beide Sprachen direkt im Code:

```python
def get_access_token(self) -> str:
    """
    Holt das aktuelle Access Token.

    Get the current access token.

    Returns:
        str: Access Token / Access token

    Raises:
        NotAuthenticatedError: Wenn nicht authentifiziert / If not authenticated
    """
    pass
```

### Struktur

```
authentication/src/questra_authentication/
├── authentication.py       # Bilinguale Docstrings
├── device_client.py        # Bilinguale Docstrings
└── exceptions.py           # Bilinguale Docstrings

docs/
├── de/                     # Deutsche Markdown-Docs
│   ├── index.md
│   └── authentication/
└── en/                     # Englische Markdown-Docs
    ├── index.md
    └── authentication/
```

### Markdown-Dokumentation

MkDocs mit mkdocs-static-i18n:

```yaml
plugins:
  - i18n:
      docs_structure: folder
      languages:
        - locale: de
          default: true
          name: Deutsch
        - locale: en
          name: English
  - mkdocstrings:
      handlers:
        python:
          options:
            docstring_style: google
```

### Vorteile

- ✅ IDE zeigt beide Sprachen an (Entwickler wählt bevorzugte)
- ✅ Keine zusätzlichen Tools für Docstring-Übersetzung
- ✅ Einfache Implementierung
- ✅ Garantierte Synchronität (beide Sprachen an einer Stelle)

### Nachteile

- ❌ Docstrings werden länger (Lesbarkeit im Code leidet)
- ❌ Manueller Übersetzungsaufwand bei jedem Docstring
- ❌ Keine Trennung zwischen Sprachen in IDE (immer beide sichtbar)
- ❌ Höherer Wartungsaufwand (beide Sprachen müssen manuell gepflegt werden)

### Wartungsaufwand

**Laufend:** Hoch
- Jeder neue/geänderte Docstring → manuelle Übersetzung
- Code-Reviews müssen beide Sprachen prüfen
- Längere Docstrings erschweren Code-Navigation

**Tooling:** Keine Automatisierung möglich

---

## Option 2: Sphinx + sphinx-intl mit PO-Dateien

### Konzept

Docstrings bleiben einsprachig (Deutsch), Übersetzungen in separaten .po-Dateien:

```python
def get_access_token(self) -> str:
    """
    Holt das aktuelle Access Token.

    Returns:
        str: Access Token
    """
    pass
```

Übersetzung in `locale/en/LC_MESSAGES/questra_authentication.po`:

```po
msgid "Holt das aktuelle Access Token."
msgstr "Get the current access token."

msgid "Access Token"
msgstr "Access token"
```

### Struktur

```
S2O.Questra.Python/
├── docs/
│   ├── conf.py              # Sphinx-Konfiguration
│   ├── index.rst
│   ├── authentication/
│   └── data/
├── locale/
│   ├── de/
│   │   └── LC_MESSAGES/
│   │       ├── questra_authentication.po
│   │       └── questra_data.po
│   └── en/
│       └── LC_MESSAGES/
│           ├── questra_authentication.po
│           └── questra_data.po
├── authentication/src/
└── data/src/
```

### Workflow

1. Code schreiben mit deutschen Docstrings
2. `sphinx-build -b gettext` → .pot-Dateien generieren
3. `sphinx-intl update -l en` → .po-Dateien aktualisieren
4. .po-Dateien übersetzen (manuell/CAT-Tool/DeepL API)
5. `sphinx-build -D language=en` → Englische Docs bauen

### Vorteile

- ✅ Professioneller Standard (gettext/PO-Format)
- ✅ CAT-Tools nutzbar (Poedit, Lokalise, Crowdin)
- ✅ DeepL/Google Translate API-Integration möglich
- ✅ Translation Memory (wiederholte Begriffe)
- ✅ Saubere Code-Basis (Docstrings bleiben kurz)
- ✅ Sphinx: Exzellente Python-Dokumentation

### Nachteile

- ❌ Kompletter Wechsel von MkDocs zu Sphinx erforderlich
- ❌ Material Theme nicht verfügbar (alternatives Theme z.B. Furo/pydata-sphinx-theme)
- ❌ IDE zeigt nur deutsche Docstrings (Übersetzung nur in generierter Doku)
- ❌ Höhere technische Komplexität (Sphinx-Setup, PO-Workflow)

### Wartungsaufwand

**Laufend:** Mittel
- Bei geänderten Docstrings: `sphinx-intl update` → nur Änderungen übersetzen
- PO-Format zeigt veraltete Übersetzungen (fuzzy-Markierung)
- Übersetzung kann teilweise automatisiert werden (DeepL API)

**Tooling:** Gute Automatisierung möglich
- Skript für DeepL-Integration
- CI-Check für unübersetzte Strings
- CAT-Tools für professionelle Übersetzung

---

## Option 3: Separate Sprachmodule

### Konzept

Code in Sprachvarianten duplizieren:

```
authentication/src/
├── questra_authentication/          # Deutsche Version
│   ├── authentication.py
│   └── device_client.py
└── questra_authentication_en/       # Englische Version
    ├── authentication.py
    └── device_client.py
```

Oder zur Build-Zeit:

```python
# Deutsch: questra_authentication.py
def get_access_token(self) -> str:
    """Holt das aktuelle Access Token."""
    pass

# Englisch: questra_authentication_en.py (generiert)
def get_access_token(self) -> str:
    """Get the current access token."""
    pass
```

### Vorteile

- ✅ IDE zeigt korrekte Sprache (abhängig vom installierten Paket)
- ✅ Saubere Trennung der Sprachen
- ✅ Keine Änderung an MkDocs nötig

### Nachteile

- ❌ Code-Duplikation (Wartungsalbtraum)
- ❌ Logik-Änderungen müssen in allen Sprachen synchronisiert werden
- ❌ Build-Prozess hochkomplex (Code-Generierung)
- ❌ Tests müssen für alle Sprachvarianten laufen
- ❌ Package-Distribution kompliziert (questra vs. questra-en)

### Wartungsaufwand

**Laufend:** Sehr hoch (nicht praktikabel)
- Jede Code-Änderung muss in allen Sprachen synchronisiert werden
- Hohes Fehlerrisiko durch Duplikation

**Tooling:** Komplex und fehleranfällig

---

## Option 4: Runtime Language Switching (Hybrid)

### Konzept

Docstrings als Dictionary, Sprache zur Laufzeit wählbar:

```python
class QuestraAuthentication:
    """
    {
        "de": "OAuth2 Authentication Client für Questra API.",
        "en": "OAuth2 authentication client for Questra API."
    }
    """

    def get_access_token(self) -> str:
        """
        {
            "de": "Holt das aktuelle Access Token.",
            "en": "Get the current access token."
        }

        Returns:
            {
                "de": "str: Access Token",
                "en": "str: Access token"
            }
        """
        pass
```

Mit Wrapper zur Laufzeit:

```python
import os
LANG = os.getenv("QUESTRA_LANG", "de")

def _(doc: str) -> str:
    """Parse JSON docstring und gib aktuelle Sprache zurück."""
    import json
    translations = json.loads(doc)
    return translations.get(LANG, translations["de"])
```

### Vorteile

- ✅ IDE zeigt Sprache basierend auf Environment-Variable
- ✅ Programmatischer Zugriff auf Übersetzungen
- ✅ Erweiterbar auf weitere Sprachen

### Nachteile

- ❌ Docstrings sind JSON (sehr schlechte Lesbarkeit)
- ❌ IDE-Parser verstehen JSON-Docstrings nicht (Tooltip-Darstellung kaputt)
- ❌ Unkonventionell (kein Standard in Python-Community)
- ❌ Komplexer Runtime-Overhead
- ❌ Tools wie mkdocstrings funktionieren nicht mehr

### Wartungsaufwand

**Laufend:** Hoch
- JSON-Syntax fehleranfällig
- Schlechte Entwickler-Erfahrung

**Tooling:** Möglich, aber hoher Implementierungsaufwand

---

## Vergleichsmatrix

| Kriterium | Option 1: Bilingual | Option 2: Sphinx+PO | Option 3: Module | Option 4: Runtime |
|-----------|---------------------|---------------------|------------------|-------------------|
| **IDE-Integration** | ✅ Beide Sprachen | ⚠️ Nur Deutsch | ✅ Korrekte Sprache | ❌ Kaputt |
| **Wartungsaufwand** | ❌ Hoch (manuell) | ✅ Mittel (tooling) | ❌ Sehr hoch | ❌ Hoch |
| **Automatisierung** | ❌ Keine | ✅ PO-Tools/DeepL | ❌ Komplex | ⚠️ Möglich |
| **Code-Lesbarkeit** | ⚠️ Länger | ✅ Sauber | ❌ Duplikation | ❌ JSON |
| **Technische Komplexität** | ✅ Einfach | ⚠️ Mittel | ❌ Hoch | ❌ Hoch |
| **Standard-Konformität** | ✅ Ja | ✅ Ja (gettext) | ❌ Nein | ❌ Nein |
| **Synchronität garantiert** | ✅ Ja | ⚠️ Manuell | ❌ Nein | ✅ Ja |

---

## Empfehlung

### Für Anforderung "Docstrings in IDE verfügbar"

**Empfohlen: Option 2 (Sphinx + sphinx-intl) + Kompromiss**

**Begründung:**
- Option 1 (Bilingual) ist einzige echte Lösung für IDE-Integration, aber Wartungsaufwand zu hoch
- Option 2 (Sphinx) bietet beste Tooling-Unterstützung, aber IDE zeigt nur Deutsch

**Kompromiss-Lösung:**

1. **Kurzfristig:** Option 1 (Bilingual) für kritische High-Level APIs
   - Nur öffentliche APIs übersetzen (QuestraAuthentication, QuestraData, QuestraDataCore)
   - Interne Klassen bleiben Deutsch
   - Reduziert Wartungsaufwand erheblich

2. **Mittelfristig:** Option 2 (Sphinx) für Gesamt-Dokumentation
   - Externe Docs vollständig übersetzt
   - Docstrings als Fallback bei fehlender IDE-Integration

### Minimaler Ansatz (Quick Win)

Bilinguale Docstrings nur für:
- `questra_authentication.QuestraAuthentication` (1 Klasse)
- `questra_data.QuestraData` (1 Klasse)
- `questra_data.QuestraDataCore` (1 Klasse)

= ~10-15 Docstrings statt ~500

Rest der Dokumentation über Sphinx + PO-Dateien.

### Alternative: IDE-Plugin entwickeln

Wenn Option 2 gewählt wird, könnte ein VSCode/PyCharm-Plugin entwickelt werden, das:
- .po-Dateien liest
- Docstring-Tooltips zur Laufzeit übersetzt

Aufwand: Hoch, aber einmalig. Nicht empfohlen für initiale Umsetzung.

---

## Nächste Schritte (bei Entscheidung)

1. **Entscheidung:** Welche Option? (Empfehlung: Option 2 + bilinguale High-Level APIs)
2. **Proof-of-Concept:** Mit `questra_authentication` testen
3. **Übersetzungsressourcen:** DeepL API vs. manuell vs. extern
4. **Rollout:** Schrittweise Migration

---

## Offene Fragen

1. Ist bilinguale Lösung für ~10 High-Level Klassen akzeptabel?
2. Reicht englische Dokumentation (Sphinx) für Entwickler aus, wenn IDE Deutsch zeigt?
3. Budget für DeepL API oder externe Übersetzung?
4. Soll Französisch parallel implementiert werden oder später?
