# ÜbersetzungsZentrale – technische Dokumentation

Die ÜbersetzungsZentrale übersetzt Texte lokal im Browser. Die Anwendung nutzt eine Provider-Architektur mit `BrowserTranslationProvider`, vorbereitetem, deaktiviertem `ServerTranslationProvider` und sicherem `DisabledTranslationProvider`.

## Bibliothek und Modelle

- Browserbibliothek: Transformers.js (`@xenova/transformers`) wird dynamisch ausschließlich im Web Worker geladen.
- Kleine Spezialmodelle: `Xenova/opus-mt-de-en` und `Xenova/opus-mt-en-de`.
- Mehrsprachiges Modell: `Xenova/m2m100_418M`.
- Unterstützte UI-Sprachen: Deutsch, Englisch, Französisch, Spanisch, Italienisch, Niederländisch, Polnisch und Portugiesisch.
- Deutsch ↔ Englisch wird bevorzugt mit den kleineren OPUS-MT-Modellen verarbeitet.
- Andere unterstützte Sprachkombinationen werden über `resolveTranslationModel()` auf das mehrsprachige M2M100-Modell geroutet.
- Quantisierung: `q8` angefordert.
- OPUS-MT-Modelle: jeweils ungefähr 74 MB im Browser-Cache.
- Das mehrsprachige Modell ist deutlich größer und wird deshalb nur geladen, wenn eine entsprechende Sprachkombination tatsächlich verwendet wird.

## Datenschutz und Netzwerkverkehr

Übersetzungstexte werden nicht als Übersetzungsanfrage an ToolZentrale, Google Translate, DeepL, Microsoft Translator oder ähnliche Serverdienste gesendet. Die Modellberechnung findet im Browser statt.

Beim ersten Bedarf werden jedoch Laufzeitcode und Modelldateien extern geladen:

- Transformers.js von jsDelivr.
- Sprachmodelle von Hugging Face beziehungsweise den von Hugging Face verwendeten Dateihosts.

Dabei entstehen bei diesen Anbietern technisch notwendige Verbindungsdaten wie IP-Adresse, Zeitpunkt, User-Agent und angeforderte Datei. Die eingegebenen Übersetzungstexte werden nach aktuellem Code nicht an diese Hosts übertragen.

Glossar, Einstellungen und optionaler Verlauf liegen im Browser. Browser-Caches können zusätzlich Modelldateien speichern.

## WebGPU und WebAssembly

Die Oberfläche prüft WebGPU, WebAssembly und Browserfähigkeiten lokal. WebGPU wird bevorzugt, WebAssembly ist Rückfall. Die Übersetzung läuft in `translation-worker.js`, damit der Hauptthread nicht durch Modellberechnung blockiert wird.

## Modellrouting

Die Modellkonfiguration liegt in `TRANSLATION_MODELS` in `src/assets/js/tools/uebersetzungszentrale/translation-core.js`.

`resolveTranslationModel(sourceLanguage, targetLanguage)` entscheidet:

1. Gleiches oder nicht unterstütztes Sprachpaar → keine Übersetzung.
2. `de-en` beziehungsweise `en-de` → kleines OPUS-MT-Spezialmodell.
3. Alle anderen unterstützten Kombinationen → `multilingual` / M2M100.

Das M2M100-Modell erhält `src_lang` und `tgt_lang` bei jedem Übersetzungsaufruf.

## Textdateien

Zusätzlich zur direkten Texteingabe können textbasierte Dateien lokal eingelesen werden:

- TXT
- Markdown
- CSV
- JSON
- XML
- LOG

Grenzen:

- maximal 2 MB Dateigröße,
- maximal 5.000 Zeichen Übersetzungstext.

Die Datei wird mit `File.text()` lokal gelesen und nicht hochgeladen.

## Modellinstallation und Löschung

Modelle werden nicht beim Öffnen der Seite geladen. Der Download startet erst bei einer tatsächlichen Übersetzungsaktion. Browser verwalten den Modellcache. Die UI bietet Schaltflächen zum Löschen lokaler Historie, Glossare und aller lokalen Übersetzungsdaten; Modelldateien werden über die Website-Daten beziehungsweise Cache-Verwaltung des Browsers entfernt.

## Schutzschicht und Prüfung

Vor der Übersetzung werden URLs, E-Mail-Adressen, Telefonnummern, Geldbeträge, Datums- und Zeitangaben, Aktenzeichen, Kennzeichen, Dateipfade, Platzhalter, HTML-Tags, Markdown-Links, Zahlen und Glossarbegriffe als `{{TZ_PROTECTED_n}}` maskiert. Nach der Übersetzung werden sie wiederhergestellt; fehlende Platzhalter führen zu einer Warnung statt zu still beschädigten Ergebnissen.

Die Prüffunktion vergleicht unter anderem:

- Zahlen,
- Geldbeträge,
- Datum/Uhrzeit,
- E-Mail-Adressen,
- URLs,
- geschützte Begriffe,
- Absatzstruktur,
- leere beziehungsweise offensichtlich unvollständige Ergebnisse.

## Neue Modelle oder Sprachen ergänzen

Neue Sprachen werden zentral in `SUPPORTED_TRANSLATION_LANGUAGES` ergänzt. Neue Spezialmodelle können unter dem Schlüssel `<quelle>-<ziel>` in `TRANSLATION_MODELS` registriert werden. Wenn kein Spezialmodell existiert, kann das mehrsprachige Modell genutzt werden, sofern es die Sprache unterstützt.

`localPath` kann später auf selbst gehostete Modellpfade zeigen, ohne die UI grundsätzlich umzubauen.

## ServerProvider

Feature-Flags liegen in `TRANSLATION_FEATURE_FLAGS`. `serverProviderEnabled` ist weiterhin `false`. Der ServerProvider baut aktuell keine Netzwerkverbindung auf und liefert bei Aktivierung ohne Konfiguration eine verständliche Fehlermeldung.

## Bekannte Einschränkungen

- Automatische Spracherkennung ist noch nicht aktiv.
- PDF-, DOCX- oder Office-Dokumentübersetzung ist nicht implementiert; aktuell werden nur textbasierte Dateien eingelesen.
- Tonfalländerung, Rückübersetzung, Audio und ein automatischer Qualitäts-Score sind nicht aktiv.
- Exakte Download-Prozentwerte werden nur angezeigt, wenn Transformers.js Fortschrittsdaten liefert.
- Browserkompatibilität hängt von Worker, WebAssembly, Speicher und optional WebGPU ab.
- Das mehrsprachige Modell benötigt erheblich mehr Speicher und Bandbreite als die beiden kleinen Deutsch/Englisch-Modelle.

## Manueller Integrationstest

1. `/tools/uebersetzungszentrale/` öffnen.
2. Deutsch → Englisch wählen und einen kurzen Text mit URL, E-Mail und Zahl übersetzen.
3. Prüfen, dass URL, E-Mail und Zahl erhalten bleiben.
4. Englisch → Deutsch wiederholen.
5. Deutsch → Französisch oder Spanisch auswählen und prüfen, dass erst dann das mehrsprachige Modell geladen wird.
6. Eine kleine TXT- oder Markdown-Datei öffnen und lokal in die Texteingabe übernehmen.
7. Verlauf aktivieren, einen Eintrag erzeugen und wieder öffnen.
8. Glossar für ein zusätzliches Sprachpaar testen.