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
• 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
• 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 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 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, such as 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

Persona resolution has two layers: content-type (what kind of text) and voice (how punchy or formal the rhythm). Both are needed.

Layer 1: Read translation_voice from .agents/oma-config.yaml

The translation_voice field controls global rhythm/formality. Three values:

| Voice | Style override applied on top of content-type | |---|---| | formal | complete sentences only, no fragments, strict 합니다체/です・ます, no padding cuts | | balanced (default) | content-type defaults; fragments allowed only in label/cell positions | | interpreter | interpreter mindset across all content types: punchy, audience-first, spoken cadence, fragments allowed when natural in target, drops formal padding ("을 받았습니다" → "받음" / "을 모두" → drop) |

If the field is missing, default to balanced. If oma-config.yaml is unreadable, also balanced.

Layer 2: Content-type persona table

| Content type | Persona | Base style markers | |---|---|---| | UI strings / microcopy | UX copywriter | concise, imperative, user-friendly | | Docs / README / API reference | technical writer | data + commentary, expanded explanations | | Benchmark / report / changelog | technical reporter | data + commentary, objective tone | | Marketing / landing / hero copy | brand copywriter | concise impact, audience-first, aggressive transcreation | | Blog post / essay | essayist | preserve cadence and rhythm, retain author voice | | Literary / prose | literary translator | preserve imagery, style consistency, narrative voice | | Dialogue / subtitle / interview | interpreter | immediacy, audience-first, spoken register, cultural context inline |

Classification heuristics:

• File location messages/, locales/, *.arb → UX copywriter
• Filename README*, docs/*, or .md with frequent code blocks → technical writer
• Score tables, benchmark stats, changelog rows → technical reporter
• Page/section hero copy → brand copywriter
• Quote marks, em-dashes, speaker labels in source → interpreter

When unclear, default to technical writer for code-adjacent content and essayist for prose. Never use a generic "translator" persona.

Combining layers

Voice is applied on top of the content-type persona. Examples:

• Content-type = technical reporter + voice = formal → fully expanded sentences, no fragments anywhere, strict 합니다체.
• Content-type = technical reporter + voice = balanced → complete sentences in body, fragments allowed in table cells (current default).
• Content-type = technical reporter + voice = interpreter → punchier rhythm, list-item fragments allowed (e.g., "39턴 / 8m 13s / $1.28 (파일당 $0.14)" instead of "39턴, 8m 13s, 총 $1.28을 썼습니다(파일당 약 $0.14)"), drops "을 모두 받았습니다" padding.

The persona is then localized to the target language at execution time. Translating into Korean as a "technical reporter" with interpreter voice means thinking as a Korean technical reporter who values rhythm and audience scan-speed over formal completeness.

Optional Layer 3: Voice sample calibration

If the user provides an author/user writing sample, analyze it before drafting. Use it as a style constraint, not as permission to alter meaning.

Extract:

• Sentence length pattern: short/punchy, long/flowing, or mixed
• Paragraph entry habit: immediate claim, context first, anecdote, question, or contrast
• Word choice level: casual, technical, academic, literary, blunt, or polished
• Punctuation habits: parentheses, colons, commas, semicolons, dashes, sparse punctuation
• Transition style: explicit connectors, abrupt turns, numbered logic, or minimal signposting
• Recurring phrases or verbal tics that are appropriate to preserve

Apply only where style matters:

• ON: blog posts, essays, speeches, interviews, marketing copy, narrative prose, adaptation requests, and user-authored documentation where preserving author voice is requested
• LIMITED: technical documentation and reports; match rhythm and terminology, but do not add personal stance
• OFF: UI strings, locale key batches, legal/official text, exact policy text, or any text where structure and fidelity outrank authorial style

Guardrail: Voice matching may adjust rhythm, diction, and sentence shape. It must not add new opinions, first-person perspective, humor, facts, examples, or emotional color that is absent from the source.

Stage 3: Reconstruct in Target Language

Rebuild from meaning as the assigned persona, following target language norms:

Word order: Follow target language's natural structure.

• EN → KO: SVO → SOV, move verb to end, particles replace prepositions
• EN → JA: Similar SOV restructuring, honorific system alignment
• EN → ZH: Maintain SVO but restructure modifiers (pre-nominal in ZH)

Register matching:

• Infer from existing translations in the project, or from source text tone
• Adjust formality markers (honorifics, sentence endings, vocabulary level)

Sentence splitting/merging:

• English compound sentences often split into shorter Korean/Japanese sentences
• English bullet points may merge into flowing paragraphs in some languages

Omission of the obvious:

• Many languages (Korean, Japanese, Chinese, etc.) allow subject or pronoun omission when contextually clear
• Don't force subjects or pronouns that feel unnatural in the target language

Stage 4: Verification Gate (blocking; do not emit output until every item is confirmed)

This stage is mandatory. Skipping any item is a bug, not a shortcut. Before producing the final translation, run the mechanical checks first, then the rubric.

A. Mechanical checks (run before rubric, must all pass):

• CJK em dash scan: For Korean, Japanese, or Chinese targets, search the draft output for —. Every occurrence must be structurally restructured, never simply substituted with : / ( / ,. Em dash usually signals a definitional X — Y pattern that maps to coordinated noun phrases, relative clauses, or separate sentences in CJK. Zero em dashes AND zero mechanical-substitution survivors in the emitted output. (See anti-AI rules 14 and 14a.)
• Curly quote scan: Search the draft output for “, ”, ‘, ’. Replace with straight quotes (", ') unless the source explicitly uses curly quotes, the target language convention requires them (e.g., Japanese 「」/『』, French «»), or the surrounding file format mandates them.
• Placeholder integrity: Every {name}, {{count}}, %s, `, and code ` from the source appears unchanged in the target.
• Structure parity: Headings, list bullets, table rows, code blocks, and links match the source count and nesting.
• Register consistency: One sentence-ending style throughout (don't mix -ㅂ니다 with -다, formal with casual).
• Sibling-pattern match (when applicable): If the target lives in a context that already contains target-language siblings (markdown table rows, locale file with sibling values, glossary entries, list items in a doc), read at least 3 siblings and identify (a) separator style: comma vs 및/와/과 vs em dash vs colon vs newline, (b) action-verb form: noun-phrase fragments vs full verb phrases vs imperative, (c) loanword density, (d) register and sentence-ending style. Your draft MUST match the dominant pattern. If the draft uses a separator/verb form/register absent from siblings, BLOCK and revise. Example failure: siblings use comma-separated noun phrases without colons; your draft uses X: Y and Z colon syntax. → revise to comma form.

If any mechanical check fails, revise and re-run. Do not proceed to the rubric until all pass.

B. Translation rubric (see resources/translation-rubric.md):

1. Does it read like it was originally written in the target language?
2. Are domain terms consistent with existing translations in the project?
3. Is the register consistent throughout?
4. Is the meaning preserved (not just words)?
5. Are cultural references adapted appropriately?
6. Are emotional connotations preserved (not flattened into neutral descriptions)?

C. Anti-AI patterns (see resources/anti-ai-patterns.md):

1. No AI vocabulary clustering or inflated significance
2. No promotional tone upgrade beyond the source
3. No synonym cycling; use consistent terminology
4. No source-language word order leaking through
5. No unnecessary bold or formatting artifacts (em dashes already covered in mechanical check A)
6. No Europeanized patterns (unnecessary connectives, passive voice, noun pile-up, over-nominalization, forced pronouns, cleft calques)
7. No humanizer-pattern leftovers: generic positive conclusions, "let's dive in" signposting, persuasive-authority tropes, formulaic "challenges/future prospects" sections, title-restating warmups, emoji decoration, or vague media/notability padding

D. Figurative language handling:

1. Were all metaphors/idioms handled per the classify decision (interpret/substitute/retain)?
2. Do figurative expressions read naturally in the target language, not as literal calques?

E. Pre-emit gate (must answer in writing before output):

Before emitting the translation, write 1–2 sentences answering each:

1. "Why is Stage 5 reflection ON or OFF for this content?": must cite the specific classification rule from the "When to run Stage 5–7" section. If the target qualifies for both ON and OFF lists (e.g., README table cell as both a short string AND documentation), default ON wins.
2. "Does my draft match the sibling patterns in the target context?": must reference at least one specific sibling and the matched (or unmatched) pattern dimension.
3. **"Is any source-language structural artifact (em dash, colon-after-X, parentheses-after-noun) m

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: first-fluke
• Source: first-fluke/oh-my-agent
• License: MIT
• Homepage: https://firstfluke.com/oh-my-agent/

Install and usage instructions live in the source repository linked above.