Translation options 

Options apply differently to the LLM and translator paths; see TranslationService.

  • 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)
  • polish (`withPolish(bool $enabled = true, ?string $instruction = null)): after a translator other than the LLM one, e.g. DeepL, ``translateWithTranslator()`` and ``translateBatchWithTranslator()`` let a language model revise the text for fluency, terminology and tone, on the default configuration or the pinned provider and model. Tags, placeholders and glossary terms must survive; when they do not, or the call fails or the budget refuses it, the first translation is returned. A guardrail stop is thrown instead. ``isPolished()`` on the result says whether the revision applied, ``metadata['polish']['reason']`` why not. The revision is recorded as a ``translation_polish`` row with the characters of the first translation sent for revision, written whether or not the answer is accepted. The revision is an ordinary request. An uncached translation with a revision normally uses two requests. User limits cover both calls; each configuration's limits apply only to calls made through that configuration. Exhausting the translator's configuration limit does not itself block a revision using another configuration. A budget refusal of the revision returns the first translation. A configuration named with ``withConfiguration()`` selects the translator only; it does not apply to the revision. The instruction goes into the system message: it must come from the calling code, never from editor input. Off by default (:ref:ADR-233 <adr-233>`)