oma-translation git:20260909.0c00b0bA

Immutable. This exact content is served forever at /api/v1/blob/da8b3c8c42eeab9a.

---
name: oma-translation
description: Context-aware translation and localization for UI strings,
  documentation, marketing copy, and prose. Preserves meaning, register,
  terminology, placeholders, structure, and natural target-language phrasing.
---

# Translation - Context-Aware Localization

## Scheduling

### Goal
Translate, review, or adapt multilingual content faithfully and naturally while preserving the
parts that must remain exact: placeholders, code, links, formatting, terminology, and file
structure.

### Intent signature
- Translate, localize, review a translation, adapt copy, or create a glossary/style guide.
- Update target-language files after the source changed.

### When to use
- UI strings, error messages, locale files, documentation, reports, marketing copy, and prose.
- Review of existing translations for accuracy, register, terminology, or naturalness.

### When NOT to use
- i18n infrastructure, locale registration, or key extraction -> use the relevant development skill.
- Date/pluralization APIs or other code-level localization -> use the owning code-domain skill.

### Expected inputs
- Source text, target language or locale, content type, and requested output mode.
- Existing locale files, glossary, surrounding context, and optional author sample.
- Placeholder and formatting constraints when the source is structured.

### Expected outputs
- Natural target-language text or evidence-backed review findings.
- Exact preservation of placeholders, code spans, links, headings, list structure, and locale keys.
- Translator notes only for meaningful ambiguity or necessary cultural explanation.

### Dependencies
- Target profile: `resources/lang/{code}.md`, if one exists.
- `resources/translation-rubric.md` for substantive content or review.
- `resources/anti-ai-patterns.md` when prose needs style review.
- Existing siblings and glossary when translating into a project.

### Control-flow features
- Branches by UI batch versus prose, profile availability, locale variant, ambiguity, and review mode.
- Loads only the target profile and references required for the content type.
- Edits files only when the user asked for file changes.

## Structural Flow

### Entry
1. Identify source, target locale, content type, and whether this is translate, review, or diff-sync.
2. Preserve exact tokens first: placeholders, code, URLs, keys, and structural markers.
3. Load the target profile if available; read sibling translations when the target is in a project.

### Scenes
1. **PREPARE**: Resolve locale, output mode, target audience, and protected syntax.
2. **ACQUIRE**: Read the target profile, relevant siblings, glossary, and source context. For prose or review, load the rubric; load anti-AI patterns only when style review is needed.
3. **REASON**: Determine meaning, register, terminology, cultural references, and any ambiguity. Decide whether an idiom should be interpreted, substituted, or retained.
4. **ACT**: Write natural target-language text. Match established project patterns without adding meaning, opinion, or personality.
5. **VERIFY**: Check protected syntax and structure. For substantive text, check meaning, terminology, register, and target-language naturalness against the rubric.
6. **FINALIZE**: Return the requested text, patch, or review with only supported findings.

### Transitions
- A profile exists -> load it; its target-language rules take precedence over shared guidance.
- A locale variant is required -> resolve it before drafting.
- No profile exists -> use shared guidance and note that limit once; do not borrow another language's rules.
- A short independent UI string with established siblings -> use protected-syntax and sibling checks; the full prose review is optional.
- Long prose, documentation, marketing copy, mixed tables/code, or review mode -> use the rubric.
- Ambiguous meaning that changes the result -> ask one targeted question or flag the choice.
- Diff-sync -> modify only source-touched equivalents, located by headings and surrounding context, not line number.

### Failure and recovery
| Failure | Recovery |
|---|---|
| Missing target context | Use the source register and state the assumption, unless the ambiguity changes meaning |
| Conflicting literal wording and project convention | Follow the established target convention and explain a material difference |
| Placeholder or structure mismatch | Revise before emitting or applying a patch |
| Missing profile | Use shared guidance and identify the coverage limit once |
| Unclear cultural reference | Add a concise note only when the target audience needs it |

### Exit
- Success: the text is faithful, natural, structurally safe, and checked in proportion to content risk.
- Partial: unresolved ambiguity or missing context is stated without inventing an answer.

### Language profile loading

Resolve the BCP 47 primary subtag and load one matching profile when present:

| Target | Profile |
|---|---|
| Korean | `resources/lang/ko.md` |
| Japanese | `resources/lang/ja.md` |
| Chinese | `resources/lang/zh.md`; resolve the declared variant |
| English | `resources/lang/en.md` |
| Other | no profile; use shared guidance |

Profiles define typography, register, and target-language checks. Shared guidance explains common
risks. A profile wins if they conflict. Add a new profile from `resources/lang/_template.md` only
when the task is to extend this skill.

### Translation method

1. Read for meaning, intended effect, domain terms, and protected syntax. Identify figurative
   wording as **interpret**, **substitute**, or **retain**. Do not add a new metaphor or remove an
   intentional one without a reason.
2. Choose register from the source, target audience, and sibling translations. Apply
   `translation_voice` from `.agents/oma-config.yaml` only as a rhythm/formality preference:
   `formal`, `balanced` (default), or `interpreter`. It never overrides meaning or target norms.
3. Reconstruct in the target language. Change word order, split or merge sentences, and omit
   implied subjects only when the target language calls for it.
4. Preserve author style only where it belongs: prose, dialogue, adaptation, or explicitly
   user-authored documentation. Match observable rhythm and diction, never add facts, stance,
   jokes, first person, or stronger emotion.

### Verification

Always check:

- Every placeholder, code span, identifier, URL, and locale key is unchanged.
- Headings, links, table rows, list nesting, and code blocks retain their structure.
- The target follows its profile's typography and register rules.
- Existing siblings are matched when they establish terminology or UI style.

For substantive content and review mode, also check the rubric: meaning, naturalness,
terminology, register, cultural fit, and emotional force. Use anti-AI patterns as a diagnostic,
not a demand to make prose decorative or to remove intentional source style.

### Review mode

Review from evidence, not from an expectation that every draft is machine-translated. Record zero
findings when no material defect is confirmed. Separate:

- **Accuracy or safety defects**: changed meaning, broken placeholder, incorrect term, or wrong register.
- **Supported style findings**: a concrete target-language issue with a reason and proposed fix.
- **Preferences**: optional alternatives that do not make the existing translation wrong.

Do not rewrite a sound translation merely to produce findings.

### Batch and diff-sync work

For batches, read the complete set first, translate values only, and maintain one terminology and
register decision. Verify placeholders and key structure across the set.

For diff-sync, map each source hunk by heading and surrounding context. Touch only the affected
target section; leave unrelated text byte-identical. State updated sections, skipped cosmetic
hunks, and material terminology decisions.

### Output formats

For a single text, present the translation and brief notes for ambiguities or adaptations. For
files, preserve the input format and modify only requested values. For review, show the original,
the suggested revision only when warranted, and the evidence for each finding.

## Logical Operations

### Actions
| Action | SSL primitive | Evidence |
|---|---|---|
| Resolve locale and mode | `SELECT` | User request and file context |
| Read profile and siblings conditionally | `READ` | Target profile, glossary, nearby translations |
| Protect syntax and structure | `VALIDATE` | Source tokens and structural markers |
| Infer meaning and register | `INFER` | Source, audience, project convention |
| Translate or revise | `WRITE` | Target text or requested file patch |
| Review substantive content | `VALIDATE` | Rubric and concrete findings |
| Report result and limits | `NOTIFY` | Translation, patch, or review |

### Tools and instruments
- Native search/read for local source and sibling translations.
- Configured `code_intelligence` capability when available for code-context navigation; native
  search/read when it is unavailable or times out.
- Target profile, rubric, anti-AI patterns, and language-template resources as selected above.

### Canonical workflow path
1. Resolve target locale and protect exact syntax.
2. Load the one applicable language profile and relevant siblings; load rubric/style resources only
   for substantive content or review.
3. Infer meaning, register, terminology, and figurative-language handling.
4. Draft in natural target order and project style.
5. Verify exact syntax and structure, then review substantive content against the rubric.
6. Emit the requested translation, patch, or evidence-backed review. State a missing-profile or
   context limitation when material.

### Resource scope
| Scope | Resource target |
|---|---|
| `LOCAL_FS` | Source/target files, glossaries, language profiles |
| `CODEBASE` | Sibling translations and code context |
| `PROCESS` | Native search and syntax checks |
| `MEMORY` | Locale, terminology, register, protected syntax, unresolved ambiguity |

### Effects and side effects
- Produces translated text or review findings.
- Changes locale/docs files only when explicitly requested.
- Retains source structure, identifiers, and placeholders.

### Guardrails
1. Preserve meaning, protected syntax, and file structure before stylistic preference.
2. Do not invent facts, opinions, emotional emphasis, examples, citations, or personality.
3. Do not use a different language's profile as a substitute.
4. Do not change untouched sections during diff-sync.
5. Do not claim completion of a check that the available source cannot support.

## References

- Translation rubric: `resources/translation-rubric.md` (load for substantive content or review)
- Style diagnostics: `resources/anti-ai-patterns.md` (load when prose style needs review)
- Target profiles: `resources/lang/{ko,ja,zh,en}.md` (load one matching profile)
- Profile template: `resources/lang/_template.md` (only when adding a profile)
- Shared context loading: `../_shared/core/context-loading.md`
- Shared quality principles: `../_shared/core/quality-principles.md`