# ChatTranslate

WoW-Addon, das fremdsprachigen Chat erkennt und automatisch ins Deutsche
übersetzt. Läuft in drei Stufen — zwei davon sofort und komplett offline im
Spiel, die dritte über ein optionales Begleitskript. Die Zielsprache ist
standardmäßig Deutsch und über `/ct lang <code>` änderbar, falls mal nötig.

## Wie es funktiert

1. **Wörterbuch, ganze Phrase** — bekannte WoW-Ausdrücke (`need a heal`,
   `inc add`, `lfg`, usw.) werden sofort erkannt und ersetzt. Kein Reload
   nötig, keine Verzögerung. Das Wörterbuch passt nur auf die **ganze**
   Nachricht 1:1 (klein geschrieben) — `"need a heal"` matched, `"i need a
   heal"` nicht mehr, weil das ein anderer String ist.
2. **Wörterbuch, einzelne Wörter** — wenn keine ganze Phrase passt, aber
   einzelne Wörter im Wörterbuch stehen, wird eine Teilübersetzung gebaut
   und mit `Ü~` markiert (Wort-für-Wort, ohne Grammatik — `"i need a heal"`
   wird so zu `"ich brauchen a heilen"`). Diese Teilübersetzung wird sofort
   angezeigt, ersetzt Stufe 3 aber **nicht** — die Nachricht wird trotzdem
   fürs Begleitskript vorgemerkt, falls eine Quellsprache erkannt wird.
3. **Warteschlange + Begleitskript** — alles, was Stufe 1 nicht abdeckt
   (auch wenn Stufe 2 schon eine grobe Teilübersetzung zeigt), wird per
   Skript- und Stopword-Erkennung einer Sprache zugeordnet und in
   `ChatTranslateDB.queue` zwischengespeichert. Das Python-Begleitskript
   (`companion/chattranslate_companion.py`) liest diese Warteschlange aus
   den SavedVariables, übersetzt offline mit **Argos Translate** und
   schreibt das Ergebnis zurück in dieselbe Datei. Taucht für eine Nachricht
   später eine fertige Begleitskript-Übersetzung auf, hat die ab dann
   **Vorrang** vor einer eventuell schon gezeigten Teilübersetzung aus
   Stufe 2 — `"i need a heal"` zeigt also erst `"ich brauchen a heilen"`
   und nach dem nächsten `/reload` die echte Übersetzung.

**Wichtig, und hier gibt's kein Schönreden:** WoW-Addons haben keinen
Netzwerkzugriff — kein `socket`, kein `http`, keine Live-Verbindung zu
irgendeinem Übersetzungsdienst. Das ist eine harte Sandbox-Grenze von
Blizzard, kein Konstruktionsfehler. SavedVariables werden außerdem nur
beim **Laden** des Addons gelesen, nicht laufend. Das heißt: Stufe-3-
Übersetzungen, die das Begleitskript geschrieben hat, siehst du im Spiel
erst nach einem `/reload`. Sofortige Live-Übersetzung über die Warteschlange
ist mit Blizzards Sandbox schlicht nicht möglich — Stufen 1 und 2 sind die
einzigen, die ohne Reload greifen.

## Installation (Addon)

1. Den Ordner `ChatTranslate/` nach
   `World of Warcraft/_retail_/Interface/AddOns/` kopieren.
2. WoW starten oder `/reload` ausführen.
3. Fertig — Stufen 1 und 2 laufen automatisch, keine Konfiguration nötig.

## Installation (Begleitskript, optional)

Nur nötig, wenn du auch Stufe 3 (alles außerhalb des Wörterbuchs) abgedeckt
haben willst.

```
pip install argostranslate
python chattranslate_companion.py "C:\...\World of Warcraft\_retail_"
```

Beim ersten Lauf für ein neues Sprachpaar lädt Argos Translate das passende
Modell aus seinem Paketindex — das braucht einmalig Internet. Danach läuft
die Übersetzung komplett offline.

Optionen:

| Flag | Bedeutung |
|---|---|
| `wow_path` | Pfad zum `_retail_`-Ordner (positional, Pflicht) |
| `--account NAME` | Account-Ordner unter `WTF/Account/`, falls mehrere vorhanden sind |
| `--watch` | läuft dauerhaft, prüft alle `--interval` Sekunden erneut |
| `--interval N` | Poll-Intervall in Sekunden für `--watch` (Standard: 30) |

Beispiel für Dauerbetrieb im Hintergrund, während du spielst:

```
python chattranslate_companion.py /pfad/zu/_retail_ --watch --interval 20
```

Nach jedem Lauf: im Spiel `/reload`, um neue Übersetzungen zu sehen.

## Slash-Befehle

| Befehl | Wirkung |
|---|---|
| `/ct on` / `/ct off` | Addon an/aus |
| `/ct lang <code>` | Zielsprache fest setzen (z. B. `de`, `en`, `fr`) |
| `/ct auto` | Zielsprache zurück auf den Standard (Deutsch) setzen |
| `/ct status` | zeigt Wörterbuch-Treffer, wartende und bereits übersetzte Nachrichten |
| `/ct clearqueue` | Warteschlange leeren |

`/chattranslate` ist ein Alias für `/ct`.

## Unterstützte Sprachen

Wörterbuch: Deutsch, Englisch, Französisch, Spanisch, Portugiesisch,
Russisch, mit einzelnen Wörtern auch Chinesisch und Koreanisch.
Skript-Erkennung (Stufe 3, für die Warteschlange): zusätzlich jede Sprache,
für die Cyrillic-, Hangul-, Hiragana/Katakana- oder CJK-Zeichen erkannt
werden, unabhängig vom Wörterbuch.

Umfang von `ChatTranslateDictionary.lua` aktuell: 142 Phrasen, 442 Wörter.
Deckt WoW-Jargon (Klassen, Rollen, Encounter-Mechaniken, Handel,
Raid-Symbole) und einfaches Alltagsvokabular ab (Begrüßung, Smalltalk,
Zahlen, Familie, Verben, Essen, Orte, Gefühle). Kein vollständiges
Wörterbuch im Langenscheidt-Sinne (zehntausende Stichwörter) — dafür ist
Stufe 3 mit Argos Translate gedacht, das ohne festes Vokabular übersetzt.

## Bekannte Grenzen

- **Kurze, wortarme Nachrichten** ohne erkennbares Wörterbuch-Wort oder
  Stopword bleiben unübersetzt und werden auch nicht in die Warteschlange
  gelegt — Beispiel: `hm` hat zu wenig Signal für eine sichere
  Sprachzuordnung. Das ist eine bewusste Schwelle gegen Falscherkennung,
  nicht ein Bug. Je größer das Wörterbuch wird, desto seltener greift
  dieser Fall allerdings — viele kurze Sätze, die früher hier
  durchgefallen wären, matchen inzwischen über Stufe 2.
- Die Stopword-Erkennung läuft nur für lateinschriftliche Sprachen
  (de/en/fr/es/pt) — kurze Sätze mit wenigen erkannten Stopwords werden
  ebenfalls nicht zugeordnet.
- Stufe 2 (Wort-Fallback) übersetzt wortweise ohne Grammatik — Ergebnisse
  wie `"ich brauchen a heilen"` sind erwartbar holprig. Das ist eine
  Übergangslösung bis die Übersetzung über Stufe 3 nachkommt, kein
  Anspruch auf korrektes Deutsch.
- Seit Stufe 2 und 3 sich nicht mehr gegenseitig ausschließen, landen mehr
  Nachrichten in `ChatTranslateDB.queue` als vorher (auch solche, die
  schon eine Teilübersetzung zeigen). Das ist gewollt — sorgt aber dafür,
  dass die SavedVariables-Datei und die Laufzeit des Begleitskripts mit
  aktiverem Chat etwas wachsen.
- Das Begleitskript parst SavedVariables mit gezielten Regex-Routinen,
  zugeschnitten auf das exakte Ausgabeformat dieses Addons — kein
  allgemeiner Lua-Parser. Bei eigenen Änderungen an der Datenstruktur in
  `ChatTranslateCore.lua` muss das Skript entsprechend angepasst werden.
- Reload-Pflicht für Stufe 3 ist eine Engine-Grenze (siehe oben), keine
  Einschränkung des Skripts selbst.
- Argos-Modell-Downloads brauchen pro neuem Sprachpaar einmalig Internet.

## Projektstruktur

```
ChatTranslate/
├── ChatTranslate/
│   ├── ChatTranslate.toc
│   ├── ChatTranslateDictionary.lua
│   └── ChatTranslateCore.lua
├── companion/
│   └── chattranslate_companion.py
└── README.md
```

Nur der `ChatTranslate/`-Unterordner gehört in `Interface/AddOns/`.
