oma-translation

# Translation - Context-Aware Localization

## 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
- Optional user/author writing sample for voice matching in prose, marketing, dialogue, or adaptation tasks
- 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` (language-neutral)
- `resources/lang/{code}.md` for the target language (required when a profile exists)
- Project locale files when translating UI strings
- User-provided voice samples when the task asks to preserve or match a specific author's style

### Control-flow features
- Branches by content type, target language, batch size, register uncertainty, and placeholder/structure requirements
- Branches by whether a language profile exists for the target, and by locale variant when the profile declares variants
- Branches by whether style-sample calibration is available and appropriate for the content type
- 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 `resources/lang/{code}.md` for the target language (see "Language Profile Loading").
3. Load existing translations, glossary, file context, or code context when available.
4. Identify placeholders, formatting constraints, and ambiguity.

### Scenes
1. **PREPARE**: Load the target language profile, then determine 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 the target language has a profile and it was not loaded, stop and load it before drafting.
- If the profile declares locale variants and none was resolved, resolve the variant before translating any string.
- If batch size is greater than 10 strings, verification is mandatory before output.
- If the output violates a typography or sentence-completion rule in the profile, 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.

### Language Profile Loading

Translation quality rules split into two layers. Load both; neither is sufficient alone.

| Layer | File | Holds |
|---|---|---|
| Shared | `resources/anti-ai-patterns.md` | AI writing pattern taxonomy, rules `1`–`25`, source-side examples |
| Shared | `resources/translation-rubric.md` | 5-criterion scoring |
| Per-language | `resources/lang/{code}.md` | Register system, language-only rules, localizations of shared rules, typography, self-check |

**Routing**: resolve the target to a BCP 47 primary subtag and read `resources/lang/{code}.md`.

| Target | Profile | Notes |
|---|---|---|
| Korean | `lang/ko.md` | rules `KO-1`–`KO-12` |
| Japanese | `lang/ja.md` | rules `JA-1`–`JA-9` |
| Chinese | `lang/zh.md` | rules `ZH-1`–`ZH-9`; **variant resolution is mandatory** before translating |
| English | `lang/en.md` | rules `EN-1`–`EN-8`; written for CJK → EN direction |
| Anything else | none yet | fall back to shared files only |

**Fallback rule**: when no profile e