Translation And Retrieval

This document describes the current translation, prompting, retrieval, and language-enrichment behavior implemented in the repository.

Related Docs

• Documentation Index
• Runtime Architecture
• Jobs And Workflow
• Quality And Review

Translation Flow At A Glance

flowchart LR
	Unit[Translation unit] --> Retrieval[Retrieve glossary, memory, and context]
	Retrieval --> Prompt[Select and render prompt template]
	Prompt --> Decision{Approved memory reused directly?}
	Decision -->|yes| Memory[Reuse stored target]
	Decision -->|no| Provider[Call mock or OpenAI-compatible provider]
	Memory --> Verify[Run segment verification]
	Provider --> Verify
	Verify --> Persist[Persist TranslationResult and VerificationResult]

Translation Provider Modes

Global Environment-Driven Provider Selection

When no provider profile is attached, services/translation/providers.py supports these global values:

• mock
• openai_compatible
• lm_studio

Provider Profiles Stored In The Database

apps/policy/models.py defines these provider profile kinds:

• mock
• openai_compatible
• private_gateway

openai_compatible and private_gateway both use the same OpenAI-compatible chat-completions client in the checked-in code.

OpenAI-Compatible Request Shape

The provider client currently:

• posts to {endpoint}/chat/completions
• sends a system prompt and a user prompt
• supports a temperature
• can add chat_template_kwargs.enable_thinking when configured
• expects a response shaped like OpenAI chat completions

Prompt Templates

Translation Prompt Template Registry

The checked-in translation prompt registry contains these profiles:

• technical_translation_short:v1
• technical_translation:v1
• technical_translation_en_bg:v1
• technical_translation_bg_en:v1

Template files live under services/translation/prompt_templates/.

Prompt Selection Rules

Current selection behavior is:

• if policy or provider config explicitly names a prompt profile, use that profile
• otherwise route short segments to technical_translation_short when available
• otherwise prefer a language-pair-specific profile such as technical_translation_en_bg
• otherwise fall back to technical_translation

Prompt config can come from either:

• LanguagePairPolicy.model_policy
• ProviderProfile.config

Supported override keys include:

• prompt_profile or prompt.profile
• prompt_version or prompt.version
• prompt_context
• prompt_budget

Language-pair policy values take precedence over provider-profile values.

Prompt Budgeting

Prompt budgeting is implemented in services/translation/prompts.py and can cap items such as:

• glossary entries
• negative glossary entries
• exact memory matches
• fuzzy memory matches
• neighboring context entries
• document-context length
• extra instruction count
• example inclusion

Each provider translation result records prompt metadata including prompt size and compaction information.

Retrieval Backends

Default Backend

The default retrieval backend is the database-backed implementation.

For each translation unit, the retrieval context can contain:

• scoped glossary matches
• exact approved-memory matches
• same-family revision-memory matches
• fuzzy approved-memory matches
• candidate-memory hints
• neighboring source texts

Optional OpenSearch Glossary Backend

When IRIS_OPEN_SEARCH_ENABLED=true, the repo switches glossary lookup to OpenSearch.

Current scope of the OpenSearch integration:

• glossary entries are synced into an OpenSearch index
• glossary searching is delegated to OpenSearch
• approved and candidate memory retrieval remain database-backed

The retrieval context records its backend name as either database or opensearch.

Scope Precedence

Glossary and memory lookup both honor three scopes:

1. document family
2. project
3. domain pack

The code ranks family matches above project matches, and project matches above domain-level matches.

Quality Evaluation At Translation Time

The rule-based evaluator currently checks:

• placeholder integrity
• number consistency
• glossary compliance
• disallowed glossary targets
• exact approved-memory consistency
• strict-review and low-resource policy flags

The evaluator can assign these immediate verification states:

• blocked
• inconsistent_with_memory
• inconsistent_with_glossary
• memory_reused
• needs_review
• glossary_verified
• ai_verified

Document Language Enrichment

Extraction runs document-level language enrichment through services/language/enrichment.py.

Current enrichment output includes:

• a document summary when summary input is available and a prompt runner is configured
• entity buckets for people, names, abbreviations, and keywords
• enrichment metadata such as truncation and character counts

The enrichment result is stored in:

• job.metadata["language_enrichment"]
• the extraction manifest JSON artifact

The translation path can reuse the stored summary as document context.

Non-Translation Prompt Families

services/language/prompts.py currently registers these prompt tasks:

• entity_keywords
• entity_people
• entity_names
• entity_abbreviations
• text_cleanup
• text_normalization
• translation_correction_en_bg
• toc_summary
• translation_evaluation_en_bg
• final_edit_bg

Template files live under services/language/prompt_templates/.