/oma-translation

name: oma-translation
description: Translate or revise localized UI strings and prose while preserving
  meaning, terminology, placeholders, and structure.

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.
• `../_shared/core/anti-ai-prose.md` and `resources/anti-ai-patterns.md` together 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; for style review, load the shared prose diagnostics and translation exceptions together. 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. Chan