# Plugin Translation Integration

Das TerraFlow Translation-System unterstützt automatisch Translations aus allen installierten Plugins.

## Plugin Translation Struktur

Plugins können Translations in folgender Struktur bereitstellen:

```
plugin/
├── CustomThemePlugin/
│   └── Resources/
│       └── translations/
│           ├── messages.de.yaml
│           └── messages.en.yaml
├── DarkThemePlugin/
│   └── Resources/
│       └── translations/
│           ├── messages.de.yaml
│           └── messages.en.yaml
└── ExamplePlugin/
    └── Resources/
        └── translations/
            ├── messages.de.yaml
            └── messages.en.yaml
```

## Plugin Translation Dateien

### Beispiel: CustomThemePlugin

```yaml
# plugin/CustomThemePlugin/Resources/translations/messages.de.yaml
custom_theme_plugin:
  title: "Theme Explorer"
  info:
    title: "Theme Information"
    description: "Hier können Sie die Standard-Templates von TerraFlow anpassen."
    status:
      title: "Status:"
      success: "Schreibberechtigung verfügbar"
      error: "Keine Schreibberechtigung"
  file_explorer:
    title: "Datei-Explorer"
    new_file: "Neue Datei erstellen"
    main_templates: "Haupt-Templates"
    no_files: "Keine Template-Dateien gefunden"
  editor:
    title: "Template-Editor"
    save_success: "Datei erfolgreich gespeichert!"
    delete_confirm: "Sind Sie sicher, dass Sie die Datei '%filename%' löschen möchten?"
```

```yaml
# plugin/CustomThemePlugin/Resources/translations/messages.en.yaml
custom_theme_plugin:
  title: "Theme Explorer"
  info:
    title: "Theme Information"
    description: "Here you can customize the default templates of TerraFlow."
    status:
      title: "Status:"
      success: "Write permission available"
      error: "No write permission"
  file_explorer:
    title: "File Explorer"
    new_file: "Create New File"
    main_templates: "Main Templates"
    no_files: "No template files found"
  editor:
    title: "Template Editor"
    save_success: "File saved successfully!"
    delete_confirm: "Are you sure you want to delete the file '%filename%'?"
```

## Verwendung in JavaScript

### Plugin-spezifische Translations

```javascript
// Plugin-Translations verwenden
const themeTitle = t('custom_theme_plugin.title');
const themeDescription = t('custom_theme_plugin.info.description');

// Mit Parametern
const deleteConfirm = t('custom_theme_plugin.editor.delete_confirm', { 
    filename: 'template.html' 
});
```

### Domain-spezifische Verwendung

```javascript
// Explizit Plugin-Domain verwenden
const title = TerraFlowTranslations.trans('title', {}, 'custom_theme_plugin');
const description = TerraFlowTranslations.trans('info.description', {}, 'custom_theme_plugin');
```

## Plugin Development

### Translation-Dateien erstellen

1. Erstelle den `Resources/translations` Ordner in deinem Plugin
2. Erstelle Translation-Dateien für alle unterstützten Sprachen
3. Verwende konsistente Schlüssel-Strukturen

### Beispiel Plugin-Struktur

```
MyPlugin/
├── src/
│   └── MyPlugin.php
├── Resources/
│   ├── views/
│   │   └── admin/
│   │       └── index.html.twig
│   └── translations/
│       ├── messages.de.yaml
│       └── messages.en.yaml
└── composer.json
```

### Translation-Schlüssel Konventionen

```yaml
# Verwende Plugin-Namen als Präfix
my_plugin:
  title: "Mein Plugin"
  description: "Plugin-Beschreibung"
  settings:
    title: "Einstellungen"
    save: "Speichern"
  actions:
    install: "Installieren"
    uninstall: "Deinstallieren"
```

## Debugging

### Console-Ausgabe

Das System zeigt automatisch Debug-Informationen in der Browser-Konsole:

```
🌐 TerraFlow Translations loaded (de)
📊 Domains: messages, admin, custom_theme_plugin, dark_theme_plugin
🔑 Total keys: 847
🔍 Translation Debug Info: {
  locale: "de",
  total_domains: 4,
  domains: ["messages", "admin", "custom_theme_plugin", "dark_theme_plugin"],
  total_keys: 847,
  loaded_at: "2024-01-15 14:30:25",
  cache_duration: 3600
}
🔌 Plugin Domains: custom_theme_plugin, dark_theme_plugin
```

### Verfügbarkeit prüfen

```javascript
// Prüfe ob Plugin-Translation existiert
if (hasTranslation('custom_theme_plugin.title')) {
    console.log('Plugin-Translation verfügbar');
}

// Alle Plugin-Domains anzeigen
const pluginDomains = TerraFlowTranslations.domains().filter(domain => 
    domain !== 'messages' && domain !== 'admin'
);
console.log('Plugin Domains:', pluginDomains);
```

## Best Practices

### 1. Konsistente Namensgebung

```yaml
# Gut - Plugin-Namen als Präfix
my_plugin:
  title: "Mein Plugin"
  settings:
    general: "Allgemein"
    advanced: "Erweitert"

# Schlecht - Kein Präfix
title: "Mein Plugin"
settings:
  general: "Allgemein"
```

### 2. Hierarchische Struktur

```yaml
# Gut - Klare Hierarchie
my_plugin:
  admin:
    title: "Plugin-Verwaltung"
    settings: "Einstellungen"
  frontend:
    title: "Plugin-Frontend"
    description: "Beschreibung"
  actions:
    install: "Installieren"
    uninstall: "Deinstallieren"

# Schlecht - Flache Struktur
my_plugin_admin_title: "Plugin-Verwaltung"
my_plugin_admin_settings: "Einstellungen"
my_plugin_frontend_title: "Plugin-Frontend"
```

### 3. Parameter verwenden

```yaml
# Translation-Datei
my_plugin:
  welcome: "Willkommen %name% im %plugin_name%"
  file_deleted: "Datei '%filename%' wurde gelöscht"
  items_count: "|0:Keine Einträge|1:Ein Eintrag|other:%count% Einträge"
```

```javascript
// JavaScript-Verwendung
const welcome = t('my_plugin.welcome', { 
    name: 'Max', 
    plugin_name: 'Mein Plugin' 
});

const fileDeleted = t('my_plugin.file_deleted', { 
    filename: 'example.txt' 
});

const itemCount = tc('my_plugin.items_count', 5, { count: 5 });
```

### 4. Fallback-Handling

```javascript
// Prüfe ob Plugin-Translation existiert
function getPluginTranslation(key, fallback = null) {
    if (hasTranslation(key)) {
        return t(key);
    }
    
    // Fallback auf Standard-Translation
    const fallbackKey = key.replace(/^[^.]+\./, 'admin.');
    if (hasTranslation(fallbackKey)) {
        return t(fallbackKey);
    }
    
    return fallback || key;
}

// Verwendung
const title = getPluginTranslation('my_plugin.title', 'Standard-Titel');
```

## Caching

- Plugin-Translations werden 1 Stunde gecacht
- Bei Änderungen an Plugin-Translation-Dateien Cache leeren
- Timestamp-Parameter für Cache-Busting

## Troubleshooting

### Plugin-Translations werden nicht geladen

1. **Prüfe Verzeichnisstruktur:**
   ```
   plugin/MyPlugin/Resources/translations/messages.de.yaml
   ```

2. **Prüfe Dateinamen:**
   - Muss `messages.{locale}.yaml` oder `messages.{locale}.yml` heißen
   - Locale muss korrekt sein (de, en, etc.)

3. **Prüfe YAML-Syntax:**
   ```bash
   # Validiere YAML-Datei
   php -r "var_dump(yaml_parse_file('messages.de.yaml'));"
   ```

4. **Prüfe Console-Logs:**
   - Browser-Konsole für Debug-Informationen
   - Server-Logs für Fehler

### Debug-Modus aktivieren

```javascript
// Debug-Modus für fehlende Translations
window.debugTranslations = true;
```

## Migration von altem System

### Vorher (statische Strings)
```javascript
const title = 'Theme Explorer';
const description = 'Customize your themes';
```

### Nachher (Plugin-Translations)
```javascript
const title = t('custom_theme_plugin.title');
const description = t('custom_theme_plugin.info.description');
```

## Features

- ✅ **Automatisches Laden** aller Plugin-Translations
- ✅ **Domain-Isolation** pro Plugin
- ✅ **Parameter-Unterstützung** für dynamische Inhalte
- ✅ **Pluralisierung** für verschiedene Sprachen
- ✅ **Fallback-Mechanismus** für fehlende Translations
- ✅ **Debug-Support** mit detaillierten Console-Logs
- ✅ **Performance-Optimierung** mit Caching
- ✅ **Symfony-Integration** mit bestehenden Plugin-Strukturen