Configuration

Extension Configuration

Open Admin Tools → Settings → Extension Configuration → nt_lingua.

Setting	Default	Description
translator	LLM (nt_ai)	Translation backend for DOM translations: LLM (nt_ai) uses the provider configured in nt-ai; DeepL uses the DeepL API directly.
deepLApiKey	(empty)	DeepL API key. Leave empty to use LLM. Supports %env(VAR)%.
deepLEndpoint	https://api-free.deepl.com/v2	DeepL API endpoint. Use https://api-free.deepl.com/v2 for the Free tier or https://api.deepl.com/v2 for a Pro subscription.

TypoScript settings

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

Setting	Default	Values	Description
sourceLanguage	de	ISO 639-1	Language of the original page content. Sent as the source language in every translation request.
translator	llm	llm, deepl	Translation backend for DOM languages. Must match the TranslatorInterface alias in Services.yaml.
offerEinfache	1	0 / 1	Show the "Einfache Sprache" option in the language switcher.
offerLeichte	0	0 / 1	Show the "Leichte Sprache" option. Only enable when a disclaimer is shown — Leichte Sprache is an AI draft and has not been verified by a certified expert.

Languages configuration

Configuration/Languages.php defines available languages and their mode:

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'],
];

Field reference:

Field	Required	Description
name	Yes	Display label in the language switcher.
rtl	Yes	true for right-to-left scripts (Arabic, Hebrew, Persian). Adds dir="rtl" and mirrors the layout.
mode	Yes	native or dom — see table below.
sysLanguageUid	native only	UID of the TYPO3 site language. Open Sites → your site → Languages to look it up.
url	native only	URL prefix matching the base field of the TYPO3 site language (e.g. /en/).

Mode:

Mode	Description
native	Real TYPO3 l10n overlay — server-rendered, indexable, own URL, hreflang
dom	Client-side DOM replacement — instant, not indexed, no page reload

Site configuration (Backend)

Under Sites → Configuration → NT Lingua tab, you can select which DOM languages are offered per site — without editing Languages.php. If the selection is empty, all mode: dom entries from Languages.php are used.

Translator backend

LLM (default)

Uses the provider configured in netthinks/nt-ai. No additional API key needed.

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)%'

Set the environment variable:

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

DeepL Free API limits

The free tier allows 500,000 characters/month. When the quota is exceeded (HTTP 456), the extension automatically falls back to the LLM translator (via nt-ai) for the remainder of the month. Rate-limit responses (HTTP 429) are retried up to three times with exponential backoff (5 / 10 / 20 s) before giving up.

Glossary

Manage entries in the TYPO3 list view, record type NT Lingua – Glossar. The storage location is arbitrary — the glossary is read globally (no pid filter) and entries may live at root level (pid=0) and on any page type. Keep all entries in one place for tidiness (e.g. a sysfolder or the root page).

target_lang	mode	Effect
fr	ignore	Leave term unchanged for French
*	ignore	Exclude term from all languages
fr	fixed	Always replace with target_term
*	fixed	Replace for all languages

Tip

For brand names in running text, <span translate="no">Brand</span> is more reliable than glossary entries, because the glossary matches whole text nodes only.

Excluding content from translation

<!-- Exclude element and all children: -->
<span translate="no">Net.Thinks</span>
<div data-nt-notranslate>This block stays untranslated</div>

Excluded HTML tags (always): <script>, <style>, <code>, <pre>, <noscript>.

AI prompts

Customize Plain Language output by editing:

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

Prompts must output only HTML using <p>, <ul>/<li>, <h2>, <strong>, <a href>. Facts, numbers and names must remain unchanged.