TranslationService 

class TranslationService

Fully qualified name

\Netresearch\NrLlm\Service\Feature\TranslationService

Language translation with quality control.

translate(string $text, string $targetLanguage, ?string $sourceLanguage = null, ?TranslationOptions $options = null): TranslationResult

Translate text to target language.

param string $text

Text to translate

param string $targetLanguage

Target language code (e.g., 'de', 'fr')

param string|null $sourceLanguage

Source language code (auto-detected if null)

param TranslationOptions|null $options

Translation options

TranslationOptions fields:

• formality: 'formal', 'informal', 'default'
• domain: 'technical', 'legal', 'medical', 'marketing', 'general'
• glossary: array of term translations
• site: site identifier (withSite()). When no glossary is set, the glossary that site keeps for the language pair applies — in the prompt on the LLM paths, as a DeepL glossary on the DeepL path (ADR-208, Managing translation glossaries)
• preserve_formatting: bool
• provider, model: pin the provider / model for this call
• configuration: identifier of a stored LlmConfiguration whose translator is used on the specialized-translator path (translateWithTranslator())
• tag_handling: html or xml (withTagHandling()). DeepL keeps the tags and translates the text between them; the LLM translator keeps tags while preserve_formatting is on (ADR-209)
• cache_ttl: seconds (withCacheTtl()). Opt-in cache for translateWithTranslator(): an identical request — translator, languages, text, glossary, options, and for the LLM translator the default configuration with its skills (no provider pinned) or the provider's default model (provider pinned, no model) — is answered from the nrllm_responses cache (tag TranslationService::CACHE_TAG) without reaching the translator, and therefore without a budget check or a usage row. Blank and truncated answers are never stored; saving or deleting a glossary, configuration, model, provider, skill or prompt snippet flushes the tag. Off by default (ADR-209)
• max_tokens: on the configuration path capped at the model's max_output_tokens when known (ADR-209)

Returns

TranslationResult

translateForConfiguration(string $text, string $targetLanguage, LlmConfiguration $configuration, ?string $sourceLanguage = null, ?TranslationOptions $options = null): TranslationResult

Translate with a stored LlmConfiguration's persona/tone.

Unlike translate, this routes through LlmServiceManager::chatWithConfiguration() so the configuration's stored system_prompt, model, provider and skills apply. translate() supplies its own system message and therefore short-circuits MessageShaper::applySystemPrompt(), so a configuration's system_prompt never reaches the model on that path. Here the translation task and constraints (target/source language, formality, glossary, "output only the translation") are layered into the user message instead, keeping the configuration's system_prompt as the system message.

Mirrors chatWithToolsForConfiguration() and embedForConfiguration().

param string $text

Text to translate

param string $targetLanguage

Target language code (e.g., 'de', 'fr')

param LlmConfiguration $configuration

The configuration whose persona/model drive the call

param string|null $sourceLanguage

Source language code (auto-detected if null)

param TranslationOptions|null $options

Translation options; temperature, max_tokens and model override the configuration's stored defaults when set. The provider field is ignored — the configuration selects the provider.

Returns

TranslationResult

translateBatch(array $texts, string $targetLanguage, ?string $sourceLanguage = null, ?TranslationOptions $options = null): array

Translate multiple texts.

param array $texts

Array of texts

param string $targetLanguage

Target language code

param string|null $sourceLanguage

Source language code (auto-detected if null)

param TranslationOptions|null $options

Translation options

Returns

array<TranslationResult>

detectLanguage(string $text, ?TranslationOptions $options = null): string

Detect the language of text.

param string $text

Text to analyze

param TranslationOptions|null $options

Translation options

Returns

string Language code (ISO 639-1)

scoreTranslationQuality(string $sourceText, string $translatedText, string $targetLanguage, ?TranslationOptions $options = null): float

Score translation quality.

param string $sourceText

Original text

param string $translatedText

Translated text

param string $targetLanguage

Target language code

param TranslationOptions|null $options

Translation options

Returns

float Quality score (0.0 to 1.0)

use Netresearch\NrLlm\Service\Feature\TranslationServiceInterface;
use Netresearch\NrLlm\Service\LlmConfigurationServiceInterface;

public function __construct(
    private readonly TranslationServiceInterface $translationService,
    private readonly LlmConfigurationServiceInterface $configurationService,
) {}

// 1. Offer the configurations the current backend user may use.
$choices = $this->configurationService->getAccessibleConfigurations();

// 2. Resolve the one the editor selected in the menu.
$configuration = $this->configurationService->getConfiguration($selectedIdentifier);

// 3. Translate with that configuration's persona/tone and model.
$result = $this->translationService->translateForConfiguration(
    $text,
    'de',
    $configuration,
    // $sourceLanguage: null => auto-detected
);