Translater

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:

Term Consistency (Glossary)

Maintain consistent translations for platform-specific terms:

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

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)