translate doku erneuert. Quickstart hinzu gemacht

doc/translate.md

@@ -2,7 +2,280 @@
 
 ## Übersicht
 
-`translate.py` ist ein Python-Tool zur Extraktion, Filterung und Übersetzung von Texten aus DXF/DWG-Dateien. Es unterstützt mehrere Arbeitsweisen und kann Texte aus verschiedenen Quellen verarbeiten.
+`translate.py` ist ein Python-Tool zur Extraktion, Filterung und Übersetzung von Texten aus DXF/DWG-Dateien. Es unterstützt mehrere Arbeitsweisen und ermöglicht die Erstellung mehrsprachiger technischer Zeichnungen für den internationalen Einsatz.
+
+---
+
+## Quickstart - Haupt-Workflow für DXF-Übersetzung
+
+Dieser Workflow beschreibt die **empfohlene Vorgehensweise** für die Übersetzung technischer Zeichnungen.
+
+### Schritt 1: Text-Extraktion aus DXF
+
+Ziehen Sie die DXF-Datei per **Drag & Drop** auf die Desktop-Verknüpfung **`tr_dxf2txt`** (Wirbelwind-Icon).
+
+**Was passiert:**
+- Alle TEXT, MTEXT und Block-Attribute (TEXT-D) werden aus der DXF extrahiert
+- Zwei Dateien werden im `work/` Ordner erstellt:
+  - `<dateiname>_texts.json` - JSON-Datei mit allen extrahierten Texten
+  - `<dateiname>_texts.txt` - Textdatei mit allen extrahierten Texten
+
+**Beispiel:**
+```
+Eingabe:  Projekt_Anlage_Rev3.dxf
+Ausgabe:  work/Projekt_Anlage_Rev3_texts.json
+          work/Projekt_Anlage_Rev3_texts.txt
+```
+
+### Schritt 2: Automatische Übersetzung mit Sprach-Config
+
+Ziehen Sie die erzeugte **JSON-Datei** (`<dateiname>_texts.json`) per **Drag & Drop** auf die gewünschte Sprach-Verknüpfung:
+
+- **tr2dxf_CS** (Tschechisch-Icon) → Tschechische Übersetzung
+- **tr2dxf_EN** (Englisch-Icon) → Englische Übersetzung
+- **tr2dxf_FR** (Französisch-Icon) → Französische Übersetzung
+- **tr2dxf_ES** (Spanisch-Icon) → Spanische Übersetzung
+- **tr2dxf_IT** (Italienisch-Icon) → Italienische Übersetzung
+
+**Was passiert:**
+- Die JSON-Datei wird mit der aktuellen Sprachkonfiguration (z.B. `CS.cfg`) re-übersetzt
+- Alle konfigurierten Begriffe werden automatisch übersetzt
+- Der `[translate]` Block in der JSON wird mit Übersetzungen gefüllt
+- Nicht-übersetzte Begriffe bleiben im `untranslated` Block
+
+**JSON-Struktur nach diesem Schritt:**
+```json
+{
+  "[CS]": {
+    "translations": [
+      {"source": "Emergency stop", "target": "Nouzové zastavení"},
+      {"source": "Power supply", "target": "Napájení"}
+    ],
+    "untranslated": [
+      {"source": "Custom text XY", "target": ""}
+    ]
+  },
+  "ignored": ["X=123.45", "LAYER=0"]
+}
+```
+
+### Schritt 3: Sichtkontrolle und manuelle Ergänzung
+
+Öffnen Sie die `_texts.json` Datei mit einem **Texteditor** oder **JSON-Editor** und prüfen Sie:
+
+1. **Translations Block:** Sind alle Übersetzungen korrekt?
+2. **Untranslated Block:** Welche Begriffe fehlen noch?
+
+Bei Bedarf:
+- Fügen Sie fehlende Übersetzungen **manuell** in die JSON ein:
+  ```json
+  {"source": "Custom text XY", "target": "Vlastní text XY"}
+  ```
+- **Oder** ergänzen Sie die Sprach-Config (`translation/CS.cfg`) und wiederholen Sie Schritt 2
+
+**Hinweis zur .txt Datei:**
+Die parallel erzeugte `.txt` Datei hat folgendes Format:
+```
+--- translations:
+
+Emergency stop -> Nouzové zastavení
+Power supply -> Napájení
+
+--- untranslated:
+
+Custom text XY
+
+--- ignored:
+
+X=123.45
+LAYER=0
+```
+
+Die `.txt` Datei eignet sich gut für einen **schnellen Überblick**, während die `.json` Datei für die tatsächliche DXF-Übersetzung verwendet wird.
+
+### Schritt 4: DXF-Datei übersetzen
+
+Ziehen Sie die **Original-DXF-Datei** per **Drag & Drop** auf die gewünschte **Sprach-Verknüpfung** (z.B. `tr2dxf_CS`).
+
+**Voraussetzung:**
+- Die `<dateiname>_texts.json` muss im `work/` Ordner vorhanden sein
+- Die JSON sollte möglichst vollständige Übersetzungen enthalten
+
+**Was passiert:**
+- Eine neue DXF-Datei wird erstellt: `<dateiname>_CS.dxf` (oder EN, FR, etc.)
+- Alle TEXT, MTEXT und Block-Attribute werden übersetzt
+- Die Übersetzungen werden in die entsprechenden Ziel-Attribute geschrieben:
+  - TEXT-D → TEXT-CS (bei Tschechisch)
+  - TEXT-D → TEXT-E (bei Englisch)
+  - TEXT-D → TEXT-ES (bei Spanisch)
+  - etc.
+- Das Original-Attribut TEXT-D bleibt **unverändert erhalten**
+
+**Beispiel:**
+```
+Eingabe:  Projekt_Anlage_Rev3.dxf (+ work/Projekt_Anlage_Rev3_texts.json)
+Ausgabe:  work/Projekt_Anlage_Rev3_CS.dxf
+```
+
+### Zusammenfassung des Workflows
+
+```
+1. DXF → [tr_dxf2txt] → _texts.json + _texts.txt
+                             ↓
+2. _texts.json → [tr2dxf_CS] → _texts.json (mit Übersetzungen)
+                             ↓
+3. Manuelle Prüfung/Ergänzung der JSON
+                             ↓
+4. DXF → [tr2dxf_CS] → DXF_CS.dxf (übersetzte Zeichnung)
+```
+
+---
+
+## Konfiguration für neue Sprachen
+
+Wenn Sie eine neue Sprache konfigurieren oder bestehende Übersetzungen erweitern möchten, folgen Sie dieser Anleitung.
+
+### Aufbau der Sprach-Konfigurationsdateien
+
+Sprach-Configs befinden sich im Verzeichnis `translation/` (z.B. `CS.cfg`, `EN.cfg`, `FR.cfg`).
+
+Jede Config-Datei hat **vier Sektionen** in festgelegter Prioritätsreihenfolge:
+
+1. **[multi]** - Phrasen mit 4 oder mehr Wörtern
+2. **[trigramme]** - Phrasen mit genau 3 Wörtern
+3. **[bigramme]** - Phrasen mit genau 2 Wörtern
+4. **[single]** - Einzelwörter
+
+**Wichtig:** Die Übersetzung erfolgt in dieser Reihenfolge. Längere Phrasen werden zuerst ersetzt, danach kürzere.
+
+### Empfohlene Vorgehensweise beim Konfigurieren
+
+#### 1. Erste Extraktion durchführen
+
+Führen Sie zunächst eine Text-Extraktion **ohne Übersetzung** durch:
+
+```bash
+bin\translate.bat --filename projekt.dxf --extract --outname projekt_texts.json
+```
+
+Dies erzeugt `projekt_texts.json` und `projekt_texts.txt` mit allen extrahierten Texten.
+
+#### 2. Zusammenhängende Phrasen identifizieren
+
+Öffnen Sie die `.txt` Datei und suchen Sie nach zusammenhängenden Phrasen:
+
+**Beispiele für zusammenhängende Phrasen:**
+- "Main distribution panel" (3 Wörter)
+- "Emergency stop button" (3 Wörter)
+- "Power supply unit" (3 Wörter)
+- "Safety circuit monitoring relay" (4 Wörter)
+
+#### 3. Konfiguration ausfüllen - Sektion [multi]
+
+Beginnen Sie mit den **längsten Phrasen** (4+ Wörter) in der `[multi]` Sektion:
+
+```ini
+[multi]
+Safety circuit monitoring relay = Relé sledování bezpečnostního obvodu
+Main circuit breaker control unit = Hlavní jistič řízení jednotky
+Emergency stop button reset function = Nouzové tlačítko funkce reset
+```
+
+**Format:** `Original = Übersetzung`
+
+#### 4. Konfiguration ausfüllen - Sektion [trigramme]
+
+Fügen Sie **3-Wort-Phrasen** in die `[trigramme]` Sektion ein:
+
+```ini
+[trigramme]
+Main distribution panel = Hlavní rozváděč
+Power supply unit = Napájecí zdroj
+Emergency stop button = Nouzové tlačítko zastavení
+Safety light curtain = Bezpečnostní světelná závěsa
+Motor protection switch = Ochrana motoru spínač
+```
+
+#### 5. Konfiguration ausfüllen - Sektion [bigramme]
+
+Fügen Sie **2-Wort-Phrasen** in die `[bigramme]` Sektion ein:
+
+```ini
+[bigramme]
+Emergency stop = Nouzové zastavení
+Power supply = Napájení
+Control panel = Ovládací panel
+Safety relay = Bezpečnostní relé
+Main switch = Hlavní spínač
+Motor protection = Ochrana motoru
+```
+
+#### 6. Konfiguration ausfüllen - Sektion [single]
+
+Fügen Sie **Einzelwörter** in die `[single]` Sektion ein:
+
+```ini
+[single]
+Weight = Hmotnost
+Cable = Kabel
+Emergency = Nouzový
+Stop = Zastavení
+Power = Napájení
+Control = Ovládání
+Safety = Bezpečnost
+Motor = Motor
+Switch = Spínač
+Panel = Panel
+```
+
+**Hinweis:** Einzelwörter werden auch innerhalb von Wörtern mit Sonderzeichen erkannt:
+- `"Weight:"` → `"Hmotnost:"`
+- `"(Motor)"` → `"(Motor)"`
+- `"\\fArial|b0;Switch"` → `"\\fArial|b0;Spínač"`
+
+### Warum diese Reihenfolge?
+
+Die Reihenfolge **Multi → Trigramme → Bigramme → Single** ist entscheidend für korrekte Übersetzungen:
+
+**Beispiel:**
+- Text: `"Emergency stop button"`
+- Falsche Reihenfolge (single zuerst):
+  - "Emergency" → "Nouzový"
+  - "stop" → "zastavení"
+  - Ergebnis: `"Nouzový zastavení button"` ❌
+
+- Richtige Reihenfolge (trigramme zuerst):
+  - "Emergency stop button" → "Nouzové tlačítko zastavení" ✓
+
+### Testen der Konfiguration
+
+Nach dem Ausfüllen der Config testen Sie die Übersetzung:
+
+```bash
+# Extraktion mit automatischer Übersetzung
+bin\translate.bat --filename projekt.dxf --extract --translate CS --outname test_cs.json
+
+# Prüfen Sie die JSON-Datei:
+# - "translations" Block: erfolgreich übersetzte Begriffe
+# - "untranslated" Block: fehlende Übersetzungen
+```
+
+Ergänzen Sie die Config basierend auf dem `untranslated` Block und wiederholen Sie den Test.
+
+### Re-Übersetzung einer bestehenden JSON
+
+Wenn Sie die Sprach-Config erweitert haben, können Sie eine bestehende JSON-Datei **re-übersetzen**:
+
+```bash
+# Manuelle Kommandozeile
+bin\translate.bat --retranslate-json projekt_texts.json --translate CS
+
+# ODER: Drag & Drop der JSON auf die Sprach-Verknüpfung (tr2dxf_CS)
+```
+
+Dies aktualisiert alle Übersetzungen basierend auf der aktuellen Config.
+
+---
 
 ## Hauptfunktionen
 
@@ -10,8 +283,11 @@
 - **Text-Filterung**: Filtert Texte basierend auf konfigurierbaren Mustern (Wildcards und Regex)
 - **Automatische Übersetzung**: Übersetzt Texte mittels konfigurierbarer Wörterbücher (Multi-Phrasen, Trigramme, Bigramme, Einzelwörter)
 - **DXF-zu-DXF Übersetzung**: Erstellt übersetzte DXF-Dateien mit mehrsprachigen Attributen
+- **Mehrsprachige Übersetzung**: Unterstützt gleichzeitige Übersetzung in mehrere Sprachen
 - **Export**: Exportiert Texte in verschiedene Formate (Excel, JSON, Text)
 
+---
+
 ## Konfigurationsdateien
 
 ### translator.cfg
@@ -37,40 +313,57 @@ FR = 0-0_TEXT-F
 
 [ignore_pattern_wildcard]
 # Wildcard-Muster für zu ignorierende Texte
-layer = LAYER=*
 coord_x = X=*
+coord_y = Y=*
+coord_z = Z=*
 # ... weitere Muster
 
 [ignore_pattern_regex]
 # Regex-Muster für zu ignorierende Texte
-decimal_number = ^-?\d+([.,]\d+)?$
+coord_arrows = ^\+\d{1,3}(?:[.,]\d{3})\s*(?:<<<|>>>)\s*\+\d{1,3}(?:[.,]\d{3})$
+ip_adress = ^.*;(\d{1,3}\.){3}\d{1,3}$
 # ... weitere Muster
 ```
 
-### Übersetzungs-Configs
+**Zweck der Sektionen:**
+- **[symbol_attribute]**: Mapping von Sprach-Codes zu DXF-Block-Attributnamen
+- **[symbol_layer]**: Mapping von Sprach-Codes zu DXF-Layer-Namen
+- **[ignore_pattern_wildcard]**: Einfache Muster mit `*` und `?` für zu ignorierende Texte
+- **[ignore_pattern_regex]**: Reguläre Ausdrücke für komplexere Filter-Muster
 
-Sprachspezifische Konfigurationsdateien im `translation/` Verzeichnis (z.B. `CS.cfg`, `EN.cfg`):
+### Übersetzungs-Configs (Beispiel: CS.cfg)
+
+Sprachspezifische Konfigurationsdateien im `translation/` Verzeichnis:
 
 ```ini
 [multi]
 # Phrasen mit 4+ Wörtern
-Main distribution panel = Hlavní rozváděč
+Safety circuit monitoring relay = Relé sledování bezpečnostního obvodu
+Main circuit breaker control unit = Hlavní jistič řízení jednotky
 
 [trigramme]
 # 3-Wort-Phrasen
+Main distribution panel = Hlavní rozváděč
 Power supply unit = Napájecí zdroj
+Emergency stop button = Nouzové tlačítko zastavení
 
 [bigramme]
 # 2-Wort-Phrasen
 Emergency stop = Nouzové zastavení
+Power supply = Napájení
+Control panel = Ovládací panel
 
 [single]
 # Einzelwörter
 Weight = Hmotnost
 Cable = Kabel
+Emergency = Nouzový
+Stop = Zastavení
 ```
 
-## Verwendung
+---
+
+## Verwendungsbeispiele (Kommandozeile)
 
 ### 1. Text-Extraktion aus DXF
 
@@ -131,9 +424,9 @@ bin\translate.bat --filename file.dxf --extract --translate EN --export-type exc
 }
 ```
 
-### 2a. Mehrsprachige Text-Extraktion
+### 3. Mehrsprachige Text-Extraktion
 
-**NEU ab Version 2025:** Extrahiert und übersetzt Texte gleichzeitig in mehrere Sprachen mit hierarchischer JSON-Struktur.
+Extrahiert und übersetzt Texte gleichzeitig in mehrere Sprachen mit hierarchischer JSON-Struktur.
 
 ```bash
 # Extraktion mit mehreren Sprachen (komma-separiert)
@@ -151,68 +444,20 @@ bin\translate.bat --filename file.dxf --extract --translate CS,EN --export-type
 {
   "[CS]": {
     "translations": [
-      {
+      {"source": "Emergency stop", "target": "Nouzové zastavení"},
-        "source": "Betriebsbereit",
+      {"source": "Weight", "target": "Hmotnost"}
-        "target": "Provozní připravenost"
-      },
-      {
-        "source": "Emergency stop",
-        "target": "Nouzové zastavení"
-      },
-      {
-        "source": "Weight",
-        "target": "Hmotnost"
-      }
     ],
     "untranslated": [
-      {
+      {"source": "Custom text", "target": ""}
-        "source": "Custom text",
-        "target": ""
-      }
     ]
   },
   "[EN]": {
     "translations": [
-      {
+      {"source": "Emergency stop", "target": "Emergency stop"},
-        "source": "Betriebsbereit",
+      {"source": "Weight", "target": "Weight"}
-        "target": "Ready for operation"
-      },
-      {
-        "source": "Emergency stop",
-        "target": "Emergency stop"
-      },
-      {
-        "source": "Weight",
-        "target": "Weight"
-      }
     ],
     "untranslated": [
-      {
+      {"source": "Custom text", "target": ""}
-        "source": "Custom text",
-        "target": ""
-      }
-    ]
-  },
-  "[FR]": {
-    "translations": [
-      {
-        "source": "Betriebsbereit",
-        "target": "Prêt à fonctionner"
-      },
-      {
-        "source": "Emergency stop",
-        "target": "Arrêt d'urgence"
-      }
-    ],
-    "untranslated": [
-      {
-        "source": "Custom text",
-        "target": ""
-      },
-      {
-        "source": "Weight",
-        "target": ""
-      }
     ]
   },
   "ignored": [
@@ -222,29 +467,7 @@ bin\translate.bat --filename file.dxf --extract --translate CS,EN --export-type
 }
 ```
 
-**Struktur:**
+### 4. DXF-zu-DXF Übersetzung
-- **`[LANG]`**: Sprachspezifische Sektion (z.B. `[CS]`, `[EN]`, `[FR]`)
-  - **`translations`**: Array mit erfolgreich übersetzten Texten
-  - **`untranslated`**: Array mit nicht übersetzten Texten (fehlende Übersetzung in Config)
-- **`ignored`**: Array mit gefilterten Texten (einmal für alle Sprachen)
-
-**Vorteile:**
-- Ein Durchlauf für alle Sprachen → schneller
-- Konsistente Extraktion für alle Sprachen
-- Übersicht über Übersetzungs-Abdeckung pro Sprache
-- Einfache Identifikation fehlender Übersetzungen
-
-**Verarbeitung mehrsprachiger JSON-Dateien:**
-
-```bash
-# Re-prozessiere mehrsprachige JSON mit zusätzlicher Sprache
-bin\translate.bat --fromjson output.json --translate CS,EN,ES
-
-# DXF-zu-DXF mit mehrsprachiger JSON (verwendet erste Sprache)
-bin\translate.bat --filename file.dxf --todxf file_cs.dxf --translate CS --translation-json multilang.json
-```
-
-### 3. DXF-zu-DXF Übersetzung
 
 Erstellt eine neue DXF-Datei mit übersetzten Texten in mehrsprachigen Attributen.
 
@@ -268,15 +491,6 @@ bin\translate.bat --filename file.dxf --todxf output.dxf --lang_source EN --tran
   - Erstellt fehlende ATTDEF im Block
   - Erstellt fehlende Layer (aus `[symbol_layer]`)
 
-### 4. Text-Filterung aus TXT-Datei
-
-Verarbeitet bereits extrahierte Texte aus einer Textdatei.
-
-```bash
-bin\translate.bat --fromtxt texts.txt --outname filtered.json
-bin\translate.bat --fromtxt texts.txt --translate CS --outname translated.xlsx
-```
-
 ### 5. JSON-Reprocessing
 
 Übersetzt den `untranslated` Block einer JSON-Datei erneut.
@@ -285,88 +499,15 @@ bin\translate.bat --fromtxt texts.txt --translate CS --outname translated.xlsx
 bin\translate.bat --fromjson output.json --translate CS
 ```
 
-## Parameter-Referenz
+### 6. JSON Re-Translation
 
-### Eingabe-Modi (mutual exclusive)
+Re-übersetzt den `translations` Block mit aktualisierter Sprach-Config.
-
-- `--extract` / `-e`: Extrahiere Texte aus DXF/DWG (benötigt `--filename`)
-- `--fromtxt FILE.txt`: Filtere Texte aus Textdatei
-- `--fromjson FILE.json`: Re-prozessiere JSON (benötigt `--translate`)
-- `--todxf OUTPUT.dxf`: DXF-zu-DXF Übersetzung (benötigt `--filename`)
-
-### Hauptparameter
-
-- `--filename FILE` / `-f FILE`: Eingabe-DXF/DWG-Datei
-- `--outname NAME` / `-o NAME`: Name der Ausgabedatei (ohne Endung bei mehreren Formaten)
-- `--translate LANG` / `-t LANG`: Übersetzungssprache (CS, EN, FR, etc.)
-- `--lang_source LANG`: Quellsprache für Block-Attribute (Standard: DE)
-- `--export-type TYPE`: Exportformat(e): `json` (Standard), `excel`, `text` oder komma-separiert (z.B. `excel,json,text`)
-- `--translation-json FILE`: JSON-Datei mit Übersetzungen für `--todxf`
-- `--debug` / `-d`: Debug-Ausgabe für Pattern-Matching
-
-## Arbeitsablauf-Beispiele
-
-### Workflow 1: Extraktion und manuelle Übersetzung
 
 ```bash
-# 1. Texte extrahieren
+bin\translate.bat --retranslate-json output.json --translate CS
-bin\translate.bat --filename project.dxf --extract --outname project_texts.json
-
-# 2. JSON manuell bearbeiten (untranslated -> translations verschieben)
-
-# 3. Übersetzte DXF erstellen
-bin\translate.bat --filename project.dxf --todxf project_cs.dxf --translate CS
 ```
 
-### Workflow 2: Automatische Übersetzung
+---
-
-```bash
-# 1. Texte extrahieren und automatisch übersetzen
-bin\translate.bat --filename project.dxf --extract --translate CS --outname project_texts.json
-
-# 2. Nicht-übersetzte Texte in JSON prüfen und manuell ergänzen
-
-# 3. Übersetzte DXF erstellen
-bin\translate.bat --filename project.dxf --todxf project_cs.dxf --translate CS
-```
-
-### Workflow 3: Mehrsprachige Dokumente
-
-```bash
-# Tschechische Version
-bin\translate.bat --filename project.dxf --todxf project_cs.dxf --translate CS
-
-# Englische Version
-bin\translate.bat --filename project.dxf --todxf project_en.dxf --translate EN
-
-# Französische Version
-bin\translate.bat --filename project.dxf --todxf project_fr.dxf --translate FR
-```
-
-## Block-Attribute und Layer
-
-### Automatische ATTDEF-Erstellung
-
-Wenn ein Block noch kein ATTDEF für das Ziel-Attribut hat:
-
-1. **ATTDEF wird erstellt** im Block-Definition
-2. **Layer wird erstellt** (falls nicht vorhanden, aus `[symbol_layer]`)
-3. **Eigenschaften werden übernommen** vom Quell-ATTDEF:
-   - Position (`insert`)
-   - Höhe (`height`)
-   - Stil (`style`)
-   - Rotation (`rotation`)
-   - Layer (aus Config oder vom Quell-Attribut)
-
-### Erforderliche Block-Attribute
-
-Blöcke müssen folgende Attribute haben, um verarbeitet zu werden:
-- `IO`
-- `ID`
-- `VERW`
-- `BEZEICHNUNG`
-- `KENNZEICHNUNG`
-- Quell-Textattribut (z.B. `TEXT-D`)
 
 ## Umgebungsvariablen
 
@@ -376,7 +517,9 @@ Das Programm benötigt folgende Umgebungsvariablen (werden in `bin/setenv.bat` g
 - `PROJECT_CFG`: Konfigurationsverzeichnis (`cfg/`)
 - `PROJECT_TRANSLATION`: Übersetzungs-Konfigurationsverzeichnis (`translation/`)
 
-## Fehlerbehandlung
+---
+
+## Fehlerbehandlung und Ausgabe
 
 Das Programm gibt detaillierte Statusmeldungen aus:
 
@@ -398,7 +541,9 @@ DXF-Übersetzung abgeschlossen:
   Gesamt: 470 übersetzt, 45 übersprungen, 0 ignoriert
 ```
 
-## Hinweise
+---
+
+## Tipps und Hinweise
 
 - Texte werden als Set verarbeitet → Duplikate werden automatisch entfernt
 - Leere Texte werden ignoriert
@@ -406,9 +551,129 @@ DXF-Übersetzung abgeschlossen:
 - Bei DXF-zu-DXF Übersetzung bleibt das Original-Attribut immer unverändert
 - Layer und ATTDEF werden nur bei Bedarf erstellt (lazy creation)
 - Alle Ausgabedateien landen im `PROJECT_WORK` Verzeichnis
+- Die `.txt` Ausgabe eignet sich für schnelle Übersicht und Textverarbeitung
+- Die `.json` Ausgabe wird für DXF-zu-DXF Übersetzung verwendet
+- Die `.xlsx` Ausgabe eignet sich für externe Übersetzungsdienstleister
+
+---
+
+## Anhang A: Python-Modul translate.py
+
+### Kommandozeilen-Parameter
+
+#### Eingabe-Modi (mutual exclusive)
+
+- `--extract` / `-e`: Extrahiere Texte aus DXF/DWG (benötigt `--filename`)
+- `--fromtxt FILE.txt`: Filtere Texte aus Textdatei
+- `--fromjson FILE.json`: Re-prozessiere JSON (benötigt `--translate`)
+- `--retranslate-json FILE.json`: Re-übersetzt translations Block mit aktueller Config (benötigt `--translate`)
+- `--todxf OUTPUT.dxf`: DXF-zu-DXF Übersetzung (benötigt `--filename`)
+
+#### Hauptparameter
+
+- `--filename FILE` / `-f FILE`: Eingabe-DXF/DWG-Datei
+- `--outname NAME` / `-o NAME`: Name der Ausgabedatei (ohne Endung bei mehreren Formaten)
+- `--translate LANG`: Übersetzungssprache (CS, EN, FR, etc.) oder mehrere kommasepariert (CS,EN,FR)
+- `--lang_source LANG`: Quellsprache für Block-Attribute (Standard: DE)
+- `--export-type TYPE`: Exportformat(e): `json` (Standard), `excel`, `text` oder komma-separiert (z.B. `excel,json,text`)
+- `--translation-json FILE`: JSON-Datei mit Übersetzungen für `--todxf`
+- `--debug` / `-d`: Debug-Ausgabe für Pattern-Matching
+
+### Wichtige Funktionen
+
+#### extract_text_from_dxf(filename, text_attr_name='TEXT-D')
+Extrahiert alle TEXT, MTEXT und Block-Attribute aus einer DXF-Datei.
+
+**Parameter:**
+- `filename`: Pfad zur DXF-Datei
+- `text_attr_name`: Name des Text-Attributs in Blöcken (Standard: "TEXT-D")
+
+**Rückgabe:**
+- Alphabetisch sortierte Liste aller gefundenen Texte (ohne Duplikate)
+
+#### filter_texts(texts, wildcard_patterns, regex_patterns, debug=False)
+Filtert Texte basierend auf Wildcard- und Regex-Mustern.
+
+**Parameter:**
+- `texts`: Liste der zu filternden Texte
+- `wildcard_patterns`: Liste der Wildcard-Muster
+- `regex_patterns`: Liste der Regex-Muster
+- `debug`: Debug-Ausgabe aktivieren
+
+**Rückgabe:**
+- Tuple mit (akzeptierte Texte, ignorierte Texte)
+
+#### translate_text(text, multi, trigramme, bigramme, single)
+Übersetzt einen Text durch Ersetzen von Multi-Phrasen, Trigrammen, Bigrammen und Einzelwörtern.
+
+**Parameter:**
+- `text`: Zu übersetzender Text
+- `multi`: Dictionary mit Multi-Wort-Phrasen
+- `trigramme`: Dictionary mit Drei-Wort-Phrasen
+- `bigramme`: Dictionary mit Zwei-Wort-Phrasen
+- `single`: Dictionary mit Einzelwörtern
+
+**Rückgabe:**
+- Übersetzter Text (leer wenn keine Übersetzung gefunden)
+
+#### translate_dxf_texts(input_dxf, output_dxf, translations, ...)
+Übersetzt alle TEXT, MTEXT Objekte und Text-Attribute in Blöcken einer DXF-Datei.
+
+**Parameter:**
+- `input_dxf`: Pfad zur Quell-DXF
+- `output_dxf`: Pfad zur Ziel-DXF
+- `translations`: Dictionary mit source -> target Mappings
+- `wildcard_patterns`: Wildcard-Muster zum Filtern
+- `regex_patterns`: Regex-Muster zum Filtern
+- `text_source_attr`: Quell-Attributname (Standard: "TEXT-D")
+- `text_target_attr`: Ziel-Attributname (Standard: "TEXT-CS")
+- `target_layer`: Ziel-Layername für neue Attribute
+
+#### retranslate_json_file(json_path, translation_dicts_all, translation_languages)
+Re-übersetzt eine JSON-Datei mit neuen Übersetzungs-Configs.
+
+**Parameter:**
+- `json_path`: Pfad zur JSON-Datei
+- `translation_dicts_all`: Dict mit {LANG: (multi, trigramme, bigramme, single)}
+- `translation_languages`: Liste der Sprachen
+
+### Interne Arbeitsweise
+
+1. **Extraktion**: Texte werden aus DXF gelesen und in einem Set gespeichert (Duplikate werden entfernt)
+2. **Filterung**: Ignore-Patterns werden angewendet (erst Wildcard, dann Regex)
+3. **Übersetzung**: Texte werden in der Reihenfolge Multi → Trigramme → Bigramme → Single übersetzt
+4. **Export**: Ergebnisse werden in gewünschte Formate geschrieben
+5. **DXF-Übersetzung**: Neue DXF wird mit übersetzten Texten erstellt (Quell-Attribute bleiben erhalten)
+
+### Block-Attribute und ATTDEF-Erstellung
+
+Wenn ein Block noch kein ATTDEF für das Ziel-Attribut hat:
+
+1. **ATTDEF wird erstellt** in der Block-Definition
+2. **Layer wird erstellt** (falls nicht vorhanden, aus `[symbol_layer]`)
+3. **Eigenschaften werden übernommen** vom Quell-ATTDEF:
+   - Position (`insert`)
+   - Höhe (`height`)
+   - Stil (`style`)
+   - Rotation (`rotation`)
+   - Layer (aus Config oder vom Quell-Attribut)
+
+### Erforderliche Block-Attribute
+
+Blöcke müssen folgende Attribute haben, um verarbeitet zu werden:
+- `IO`
+- `ID`
+- `VERW`
+- `BEZEICHNUNG`
+- `KENNZEICHNUNG`
+- Quell-Textattribut (z.B. `TEXT-D`)
+
+---
 
 ## Siehe auch
 
 - [CLAUDE.md](../CLAUDE.md) - Allgemeine Projektdokumentation
 - `cfg/translator.cfg` - Hauptkonfiguration
 - `translation/*.cfg` - Sprachspezifische Übersetzungs-Configs
+- `bin/tr2dxf.bat` - Zentrale Batch-Datei für Übersetzungen
+- `bin/tr2dxf_*.bat` - Sprachspezifische Wrapper-Skripte