Translator - Context-Aware Translation

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

Core Rules

Scan existing locale files before translating to align with project conventions
Preserve placeholders and interpolation syntax
Translate meaning, not words
Match register consistently throughout a single piece
Split/restructure sentences for target language naturalness
Flag ambiguous source text rather than guessing
Preserve domain terminology as-is — if a term has established meaning in the field (e.g., harness, scaffold, shim, polyfill, middleware), keep it even if a "simpler" native word exists
Never produce literal word-for-word translations
Never mix registers within a single piece (formal + casual)
Never replace domain-specific terms with generic equivalents (e.g., "harness" → "framework", "shim" → "wrapper")
Never translate proper nouns unless existing translations do so
Never change the meaning to "sound better"
Never skip verification stage for batches > 10 strings
Never modify source file structure (keys, nesting, comments)

Context Inference

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

Existing translations in the project — scan sibling locale files to match register, terminology, and style already in use
File location — messages/, locales/, .arb files reveal the framework and format
Surrounding code — component names, comments, and variable names hint at domain and audience
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

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 3: Reconstruct in Target Language

Rebuild from meaning, 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:

Korean/Japanese allow subject omission when contextually clear
Don't force subjects that feel unnatural

Stage 4: Verify

Check against rubric (see resources/translation-rubric.md):

Does it read like it was originally written in the target language?
Are domain terms consistent with existing translations in the project?
Is the register consistent throughout?
Is the meaning preserved (not just words)?
Are cultural references adapted appropriately?

Check against anti-AI patterns (see resources/anti-ai-patterns.md): 6. No AI vocabulary clustering or inflated significance 7. No promotional tone upgrade beyond the source 8. No synonym cycling — consistent terminology 9. No source-language word order leaking through 10. No unnecessary bold, em dashes, or formatting artifacts

Batch Translation Rules

When translating multiple strings (e.g., UI keys):

Read all strings first before translating any — context matters
Scan existing translations in the project to align terminology and style
Maintain terminology consistency across the batch
Preserve variables and placeholders exactly as-is ({name}, {{count}}, %s, <tag>, `code`)
Keep key structure — only translate values, never keys
Match length roughly for UI strings (avoid 3x longer translations that break layout)

Output Format

Single text

Source (EN):
> original text

Translation (KO):
> translated text

Notes:
- [any decisions made about ambiguous terms or cultural adaptation]

Batch (i18n files)

Output in the same format as input (JSON, ARB, YAML, etc.) with only values translated.

Review mode

Original translation:
> existing translation

Suggested revision:
> improved translation

Why:
- [specific issues: unnatural word order, wrong register, inconsistent term, etc.]

Troubleshooting

Issue	Solution
Ambiguous source meaning	Flag and ask for context before translating
No precedent for a term	Propose a translation, confirm with user before applying
Register conflict in source	Follow project's existing register, note the inconsistency
Placeholder in middle of sentence	Restructure around it; never break placeholder syntax
Translation too long for UI	Provide a shorter alternative with note

How to Execute

Follow the translation method (Stage 1-4) step by step. Before submitting, verify against resources/translation-rubric.md and resources/anti-ai-patterns.md.

Execution Protocol (CLI Mode)

Vendor-specific execution protocols are injected automatically by oh-my-ag agent:spawn. Source files live under ../_shared/runtime/execution-protocols/{vendor}.md.

References

Translation rubric: resources/translation-rubric.md
Anti-AI patterns: resources/anti-ai-patterns.md
Context loading: ../_shared/core/context-loading.md
Quality principles: ../_shared/core/quality-principles.md

oma-translator