Konfiguration¶

Extension-Konfiguration¶

Admin Tools → Einstellungen → Extension-Konfiguration → nt_lingua öffnen.

Einstellung	Standard	Beschreibung
`translator`	LLM (nt_ai)	Übersetzungs-Backend für DOM-Sprachen: `LLM (nt_ai)` verwendet den in nt-ai konfigurierten Provider; `DeepL` spricht die DeepL-API direkt an.
`deepLApiKey`	(leer)	DeepL-API-Key. Leer lassen, um LLM zu verwenden. Unterstützt `%env(VAR)%`.
`deepLEndpoint`	`https://api-free.deepl.com/v2`	DeepL-API-Endpunkt. Free-Tier: `https://api-free.deepl.com/v2`, Pro-Abo: `https://api.deepl.com/v2`.

TypoScript-Einstellungen¶

plugin.tx_ntlingua.settings {
    sourceLanguage = de
    translator     = llm
    offerEinfache  = 1
    offerLeichte   = 0
}

Einstellung	Standard	Werte	Beschreibung
`sourceLanguage`	`de`	ISO 639-1	Sprache des Original-Seiteninhalts. Wird bei jedem Übersetzungsaufruf als Quellsprache übergeben.
`translator`	`llm`	`llm`, `deepl`	Übersetzungs-Backend für DOM-Sprachen. Muss mit dem `TranslatorInterface`-Alias in `Services.yaml` übereinstimmen.
`offerEinfache`	`1`	`0` / `1`	Option „Einfache Sprache" im Sprachwähler anzeigen.
`offerLeichte`	`0`	`0` / `1`	Option „Leichte Sprache" anzeigen. Nur aktivieren, wenn ein Disclaimer sichtbar ist — die Ausgabe ist ein KI-Entwurf und wurde nicht von einer zertifizierten Fachkraft geprüft.

Sprachkonfiguration¶

Configuration/Languages.php definiert die verfügbaren Sprachen und ihren Modus:

return [
    'en' => [
        'name'           => 'English',
        'rtl'            => false,
        'mode'           => 'native',
        'sysLanguageUid' => 1,
        'url'            => '/en/',
    ],
    'fr' => ['name' => 'Français', 'rtl' => false, 'mode' => 'dom'],
    'ar' => ['name' => 'العربية',  'rtl' => true,  'mode' => 'dom'],
];

Feldreferenz:

Feld	Pflicht	Beschreibung
`name`	Ja	Anzeigename im Sprachwähler.
`rtl`	Ja	`true` für Rechts-nach-links-Schriften (Arabisch, Hebräisch, Persisch). Setzt `dir="rtl"` und spiegelt das Layout.
`mode`	Ja	`native` oder `dom` — siehe Tabelle unten.
`sysLanguageUid`	nur `native`	UID der TYPO3-Site-Sprache. Nachschlagen unter Sites → Site → Sprachen.
`url`	nur `native`	URL-Präfix aus der TYPO3-Site-Konfiguration (z. B. `/en/`). Muss mit dem `base`-Feld der Site-Sprache übereinstimmen.

Modus:

Modus	Beschreibung
`native`	Echtes TYPO3-l10n-Overlay — server-gerendert, indexierbar, eigene URL, hreflang
`dom`	Client-seitige DOM-Ersetzung — sofort, nicht indexiert, kein Seitenneulade

Site-Konfiguration (Backend)¶

Unter Sites → Konfiguration → Tab NT Lingua können die angebotenen DOM-Sprachen pro Site ausgewählt werden — ohne Languages.php anzupassen. Ist die Auswahl leer, werden alle mode: dom-Einträge aus Languages.php verwendet.

Übersetzungs-Backend¶

LLM (Standard)¶

Verwendet den in netthinks/nt-ai konfigurierten Provider. Kein zusätzlicher API-Key erforderlich.

In Configuration/Services.yaml:

Netthinks\NtLingua\Translator\TranslatorInterface:
  alias: Netthinks\NtLingua\Translator\LlmTranslator

DeepL¶

Netthinks\NtLingua\Translator\TranslatorInterface:
  alias: Netthinks\NtLingua\Translator\DeepLTranslator

Netthinks\NtLingua\Translator\DeepLTranslator:
  arguments:
    $apiKey: '%env(NTLINGUA_DEEPL_KEY)%'

Umgebungsvariable setzen:

# .ddev/config.yaml
web_environment:
  - NTLINGUA_DEEPL_KEY=your-deepl-api-key

DeepL Free API — Zeichenlimit

Das Free-Tier erlaubt 500.000 Zeichen/Monat. Bei Überschreitung (HTTP 456) wechselt die Extension automatisch auf den LLM-Übersetzer (via nt-ai) — für alle weiteren Anfragen im laufenden Monat. Rate-Limit-Antworten (HTTP 429) werden bis zu dreimal mit exponentiellem Backoff (5 / 10 / 20 s) wiederholt.

Glossar¶

Einträge in der TYPO3-Listenansicht pflegen, Datensatztyp NT Lingua – Glossar. Der Ablageort ist frei wählbar — das Glossar wird global gelesen (kein pid-Filter), Einträge dürfen auf Root-Level (pid=0) und auf jedem Seitentyp liegen. Der Übersichtlichkeit halber alle Einträge an einem Ort halten (z. B. ein SysOrdner oder die Root-Seite).

`target_lang`	`mode`	Verhalten
`fr`	`ignore`	Begriff für Französisch unverändert lassen
`*`	`ignore`	Begriff für alle Sprachen ausschließen
`fr`	`fixed`	Begriff immer durch `target_term` ersetzen
`*`	`fixed`	Ersetzung für alle Sprachen

Tip

Für Markennamen in Fließtext ist <span translate="no">Marke</span> zuverlässiger als Glossar-Einträge, da der Glossar-Check nur auf ganze Text-Knoten angewandt wird.

Inhalte von der Übersetzung ausschließen¶

<!-- Element und alle Kindelemente ausschließen: -->
<span translate="no">Net.Thinks</span>
<div data-nt-notranslate>Dieser Block bleibt unübersetzt</div>

Immer ausgeschlossene HTML-Tags: <script>, <style>, <code>, <pre>, <noscript>.

KI-Prompts¶

Die Ausgabe der Einfachen/Leichten Sprache kann durch Bearbeiten folgender Dateien angepasst werden:

Resources/Private/Prompts/einfache.txt — Einfache Sprache
Resources/Private/Prompts/leichte.txt — Leichte Sprache

Die Prompts müssen ausschließlich HTML mit <p>, <ul>/<li>, <h2>, <strong>, <a href> ausgeben. Fakten, Zahlen und Namen müssen unverändert bleiben.