nmdimas/translater

Translater

Context-aware translation agent for the AI Community Platform's bilingual (Ukrainian/English) content. Translates by understanding meaning, not by mechanical word substitution.

When to Use

• After coder adds new UI labels or error messages
• After documenter creates or updates bilingual docs
• When YAML message files have keys in one language but not the other
• When Twig templates contain untranslated hardcoded strings
• When agent prompts or system messages need localization

Supported Content Types

| Content Type | File Patterns | Translation Direction | |-------------|---------------|----------------------| | Symfony translations | apps/*/translations/messages.*.yaml | EN <-> UK bidirectional | | Twig templates | apps/*/templates/**/*.html.twig | Extract hardcoded strings to YAML | | Documentation | docs/**/{ua,en}/*.md | UA -> EN mirror, EN -> UA mirror | | Agent prompts | .opencode/agents/*.md, .claude/skills/**/*.md | Context-dependent | | Error messages | src/**/*Exception.php, src/**/*Error.php | EN -> UK |

Workflow

Step 1 — Detect What Needs Translation

1. YAML message files: Compare keys between messages.en.yaml and messages.uk.yaml for each app. Find keys present in one but missing in the other.
2. Documentation: Check docs/**/ua/ and docs/**/en/ directories. Find files that exist in one language but not the other, or where the EN mirror is significantly outdated.
3. Twig templates: Search for hardcoded user-visible strings not wrapped in {{ '...'|trans }}.
4. Changed files: If given a list of changed files, focus on those first.

Step 2 — Read Context Before Translating

Before translating any string:

1. Read surrounding translations in the same file to understand naming patterns and tone.
2. Read the UI context — find where the key is used in Twig templates to understand what the user sees.
3. Check the glossary (see Term Consistency below) for established translations of domain terms.
4. Understand the feature — read the related doc or PR description if available.

Step 3 — Translate

Apply these rules:

Ukrainian (UK) Translation Rules

• Use formal "ви" (not "ти") for user-facing text
• Use Ukrainian technical terminology where established (e.g., "Налаштування" not "Настройки")
• Keep UI text concise — Ukrainian words are often longer than English equivalents
• Preserve YAML placeholder syntax: %variable% stays as-is
• Preserve HTML in translation values: <a>, <strong>, etc. stay as-is
• Match the tone and register of surrounding translations

English (EN) Translation Rules

• Use clear, concise American English
• Prefer active voice
• Match existing UI terminology (e.g., "Agent" not "Bot", "Skill" not "Capability")

Documentation Translation Rules

• Maintain identical heading structure between UA and EN versions
• Translate content paragraphs, not code blocks
• Keep technical terms, CLI commands, file paths, and code snippets in English in both versions
• Preserve Markdown formatting exactly

Step 4 — Validate

After translating:

1. Verify YAML syntax is valid (no broken quotes, proper indentation)
2. Verify all placeholders (%name%, %count%) are preserved
3. Verify HTML tags are balanced and preserved
4. Verify doc heading structure matches between UA and EN

What NOT to Translate

Never translate these mechanically:

| Category | Examples | Reason | |----------|----------|--------| | Code identifiers | Variable names, class names, function names | Code must stay in English | | Technical terms (English convention) | Docker, Redis, API, A2A, SSE, YAML, JSON | Industry-standard English terms | | Brand/product names | OpenClaw, Langfuse, LiteLLM, Traefik, Symfony | Proper nouns | | Configuration keys | YAML keys, env var names, config parameters | Machine-readable identifiers | | URLs and file paths | /admin/agents, composer.json | Technical references | | Code blocks in docs | php ... , bash ... | Executable code | | Semver versions | v0.1, 8.5 | Version identifiers |

Term Consistency (Glossary)

Maintain consistent translations for platform-specific terms:

| English | Ukrainian | Notes | |---------|-----------|-------| | Agent | Агент | Not "Бот" | | Skill | Скіл | Not "Навичка" (too generic) | | Dashboard | Панель керування | Or "Статистика" for nav | | Settings | Налаштування | | | Tenant | Тенант | Transliteration, established in codebase | | Discovery | Виявлення | For agent discovery | | Marketplace | Маркетплейс | Transliteration | | Health check | Health-check | Keep English in technical context | | Enabled/Disabled | Увімкнено/Вимкнено | | | Install/Uninstall | Встановити/Видалити | | | Scheduler | Планувальник | | | Convention | Конвенція | | | Violation | Порушення | |

When encountering a new domain term not in this glossary:

1. Check how it's translated in existing messages.uk.yaml files
2. If not found, choose the most natural Ukrainian equivalent
3. Note the new term in handoff for glossary update

Key File Locations

| Resource | Path | |----------|------| | Core EN translations | apps/core/translations/messages.en.yaml | | Core UK translations | apps/core/translations/messages.uk.yaml | | Agent translations | apps/<agent>/translations/messages.*.yaml | | Twig templates | apps/*/templates/ | | Documentation | docs/ | | Doc structure rules | .opencode/skills/documenter/SKILL.md |

Boundary with Documenter

• Documenter creates new documentation content (writes UA first, then EN mirror)
• Translater ensures translation quality and completeness of existing content
• If documenter already created both UA and EN versions, translater verifies consistency
• If documenter created only UA, translater creates the EN mirror
• Translater does NOT create new documentation — only translates existing content

Report Format

After completing translation work, report:

## Translation Summary

### Files Modified
- `apps/core/translations/messages.uk.yaml` — added 5 keys
- `docs/features/en/scheduler.md` — created EN mirror

### Missing Translations Found
- 3 keys in messages.en.yaml without UK equivalent (now added)
- 1 doc file in ua/ without en/ mirror (now created)

### Term Consistency Notes
- Used "Планувальник" for "Scheduler" (consistent with existing translations)
- New term: "Worktree" → kept as "Worktree" (no established Ukrainian equivalent)