oma-translator

# Translator - Context-Aware Translation

## Scheduling

### Goal
Translate, review, or adapt multilingual content while preserving meaning, register, placeholders, structure, domain terminology, and natural target-language word order.

### Intent signature
- User asks to translate, localize, review translation quality, create a glossary, or adapt UI/docs/marketing copy.
- User needs context-aware translation rather than mechanical word substitution.

### When to use

- Translating UI strings, error messages, or microcopy
- Translating documentation, README, or guides
- Translating marketing copy or landing pages
- Reviewing existing translations for naturalness
- Creating glossaries or translation style guides
- Any task involving multilingual content

### When NOT to use

- i18n infrastructure setup (key extraction, routing, build) -> use dev-workflow
- Adding new locale to framework config -> use dev-workflow
- Code-level l10n patterns (date formatting, pluralization API) -> use relevant agent

### Expected inputs
- Source text, target language, and optional locale or audience
- Existing locale files, glossary, code context, or style constraints
- Placeholder syntax, formatting constraints, and output mode

### Expected outputs
- Natural target-language translation or review findings
- Preserved placeholders, code spans, links, headings, lists, and file structure
- Translator notes when source concepts need explanation
- Batch-safe output for i18n files when requested

### Dependencies
- Existing translations and surrounding code for register and terminology
- `resources/translation-rubric.md` and `resources/anti-ai-patterns.md`
- Project locale files when translating UI strings

### Control-flow features
- Branches by content type, target language, batch size, register uncertainty, and placeholder/structure requirements
- Reads locale files and source context; may write translated content only when explicitly editing files
- Blocks output until mechanical verification passes

## Structural Flow

### Entry
1. Confirm source text, target language, content type, and output mode.
2. Load existing translations, glossary, file context, or code context when available.
3. Identify placeholders, formatting constraints, and ambiguity.

### Scenes
1. **PREPARE**: Determine language, register, domain, and structure constraints.
2. **ACQUIRE**: Read existing translations and surrounding context.
3. **REASON**: Analyze source meaning, connotations, figurative language, and terminology.
4. **ACT**: Reconstruct natural target-language output.
5. **VERIFY**: Run mechanical checks and translation rubric.
6. **FINALIZE**: Emit translation, review notes, or file changes.

### Transitions
- If context is insufficient, ask one targeted question.
- If batch size is greater than 10 strings, verification is mandatory before output.
- If CJK output contains em dashes or source-language artifacts, rewrite before final output.
- If placeholders or structure do not match, revise and rerun verification.

### Failure and recovery
- If source meaning is ambiguous, flag ambiguity rather than guessing.
- If project conventions conflict with literal translation, follow project conventions and explain if needed.
- If file structure is risky to modify, preserve structure and limit edits to values.

### Exit
- Success: target text is natural, faithful, structurally equivalent, and verified.
- Partial success: ambiguous source text or missing context is explicit.

### Context Inference

No config file required. Instead, infer translation context from:

1. **Existing translations in the project** — scan sibling locale files to match register, terminology, and style already in use
2. **File location** — `messages/`, `locales/`, `.arb` files reveal the framework and format
3. **Surrounding code** — component names, comments, and variable names hint at domain and audience
4. **Source text itself** — register, formality, sentence structure reveal intent

If context is insufficient to make a confident decision, ask the user. Prefer one targeted question over a batch of questions.

### Translation Method

### Stage 1: Analyze Source

Read the source text and identify:
- **Register**: Formal, casual, conversational, technical, literary
- **Intent**: Inform, persuade, instruct, entertain
- **Domain terms**: Words that need consistent translation (check existing translations first)
- **Cultural references**: Idioms, metaphors, humor that won't transfer directly
- **Sentence rhythm**: Short/punchy vs. long/flowing — note parallel structures, intentional repetition, and emphasis patterns
- **Comprehension challenges**: Terms or references target readers may struggle with — domain jargon lacking standard translations, cultural references (pop culture, history, social norms), implicit knowledge the author assumes, wordplay or puns, named concepts (e.g., "Dunning-Kruger effect"). For each, note: the original term, why it may confuse, and a concise plain-language explanation for a potential translator's note
- **Figurative language mapping**: For each metaphor, simile, idiom, or figurative expression, classify the handling approach:
  - **Interpret**: Discard source image entirely, express the intended meaning directly in natural target language
  - **Substitute**: Replace with a target-language idiom or image that conveys the same idea and emotional effect
  - **Retain**: Keep the original image if it works equally well in the target language
- **Emotional connotations**: Words carrying subjective feeling beyond dictionary meaning (e.g., "alarming" = urgency, "haunting" = lingering unease) — note the emotional effect to preserve in translation

### Stage 2: Extract Meaning

Strip away source language structure. Ask yourself:
- What is the author actually trying to say?
- What emotion or tone should the reader feel?
- What action should the reader take?

Do NOT start forming target sentences yet.

### Stage 2.5: Persona Assignment

Pers