---
title: "ADR-019: Internationalization Strategy"
manual: "TYPO3 LLM Extension"
version: "0.35"
permalink: "https://docs.typo3.org/permalink/netresearch/nr-llm:adr-019@0.35"
source: "Adr/Adr019InternationalizationStrategy.rst"
modified: "2026-09-16T22:09:16+00:00"
---

# ADR-019: Internationalization Strategy

-   *Status:* Accepted
-   *Date:* 2025-12
-   *Authors:* Netresearch DTT GmbH

## Context

The backend module needs multi-language support for all
UI elements. Additionally, LLM-powered features (test
prompts, wizard descriptions) should respect the backend
user's locale so that responses arrive in the expected
language.

## Decision

Follow TYPO3 XLIFF conventions for static UI strings and add locale-aware
placeholder substitution for dynamic LLM interactions.

### XLIFF label files

One XLIFF file per backend module, plus German translations:

| File | Scope |
| --- | --- |
| locallang.xlf / de.locallang.xlf | Shared labels, flash messages |
| locallang_tca.xlf / de.locallang_tca.xlf | TCA field labels and descriptions |
| locallang_mod.xlf / de.locallang_mod.xlf | Main module navigation |
| locallang_mod_provider.xlf / de.\* | Provider sub-module |
| locallang_mod_model.xlf / de.\* | Model sub-module |
| locallang_mod_config.xlf / de.\* | Configuration sub-module |
| locallang_mod_task.xlf / de.\* | Task sub-module |
| locallang_mod_wizard.xlf / de.\* | Setup Wizard sub-module |
| locallang_mod_overview.xlf / de.\* | Overview/Dashboard sub-module |

### Locale-aware LLM features

The `TestPromptResolverService` (a `final readonly class` implementing
`TestPromptResolverInterface`, injected via DI — it replaced the former
`TestPromptTrait` when the logic was extracted out of the controller) resolves
the backend user's language and substitutes a `{lang}` placeholder in
configurable test prompts:

**TestPromptResolverService locale resolution**

```php
public function resolve(): string
{
    // Reads the configurable prompt (default: "Say hello and introduce
    // yourself in one sentence. Respond in {lang}.") and the BE user's language.
    $prompt       = $this->loadConfiguredPrompt();
    $languageName = self::LANGUAGE_MAP[$this->resolveBackendUserLanguage()] ?? 'English';

    return str_replace('{lang}', $languageName, $prompt);
}
```

Language mapping covers 27 locales (English, German, French, Spanish, Italian,
Dutch, Portuguese, Danish, Swedish, Norwegian, Finnish, Polish, Czech, Slovak,
Hungarian, Romanian, Bulgarian, Croatian, Slovenian, Greek, Turkish, Russian,
Ukrainian, Chinese, Japanese, Korean, Arabic) with English as fallback.

The test prompt text itself is configurable via TYPO3 extension configuration
(`$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_llm']['testing']['testPrompt']`),
allowing administrators to customize it while preserving
the `{lang}` placeholder.

## Consequences

**Positive:**

-   ●● Standard TYPO3 XLIFF approach ensures compatibility with the Translation
    Handling system and third-party translation tools.
-   ● German translations shipped as first non-English locale.
-   ● Locale-aware test prompts produce responses in the user's language.
-   ◐ Configurable test prompt allows site-specific customization.
-   ◐ `{lang}` placeholder pattern is extensible to other features.

**Negative:**

-   ◑ Additional XLIFF files increase maintenance surface per feature.
-   ◑ Language name mapping requires manual updates for new TYPO3 locales.

**Net Score:** +5.0 (Strong positive)

## Files changed

**Added:**

-   `Resources/Private/Language/locallang.xlf` and `de.locallang.xlf`
-   `Resources/Private/Language/locallang_tca.xlf`
    and `de.locallang_tca.xlf`
-   `Resources/Private/Language/locallang_mod.xlf`
    and `de.locallang_mod.xlf`
-   `Resources/Private/Language/locallang_mod_provider.xlf` and `de.*`
-   `Resources/Private/Language/locallang_mod_model.xlf` and `de.*`
-   `Resources/Private/Language/locallang_mod_config.xlf` and `de.*`
-   `Resources/Private/Language/locallang_mod_task.xlf` and `de.*`
-   `Resources/Private/Language/locallang_mod_wizard.xlf` and `de.*`
-   `Resources/Private/Language/locallang_mod_overview.xlf` and `de.*`
-   `Classes/Service/TestPromptResolverService.php` and
    `Classes/Service/TestPromptResolverInterface.php`