translation-workflow

name	translation-workflow
description	Run the backend_to_ml translation pipeline (extract → translate → apply → validate). Triggered when the user mentions .po, gettext, msgstr, fuzzy, sync-translations, translate-with-ai, validate-translation, or after writing new src/*.md content.

Translation workflow

backend_to_ml is a 3-language mdBook (uz default, ru, en). Translations live in po/ru.po and po/en.po in gettext format. msgids are extracted from src/*.md; msgstrs are the translations.

5-step pipeline

1. Sync (refresh msgids)

After editing src/*.md, update the po files:

./scripts/sync-translations.sh

Internally:

• extract-messages.sh → regenerates po/messages.pot
• msgmerge → updates po/ru.po, po/en.po (new msgids appended, changed ones marked #, fuzzy)

2. Extract a batch (optional)

For larger translation runs, pull pending strings into JSON:

uv run python scripts/extract-pending-batch.py po/ru.po \
  --filter "month-01-*" --count 200 \
  --output translations/ru-m01-batch.json

The filter matches msgid occurrences (file paths). Picks up both untranslated and fuzzy strings.

3. AI translation

export ANTHROPIC_API_KEY=sk-ant-...
uv run python scripts/translate-with-ai.py po/ru.po \
  --filter "month-01-*" --max-strings 100

• Default model: Claude Haiku 4.5
• Applies the 100+ standardized terms from po/glossary.yaml
• Skips words in the do_not_translate list
• Batches 30 strings per API call
• --retranslate-fuzzy — re-translates only entries marked fuzzy

Alternative: fill the JSON by hand, then run:

uv run python scripts/apply-translations.py po/ru.po translations/ru-m01-batch.json

4. Validate

uv run python scripts/validate-translation.py po/ru.po --strict

Checks:

• Markdown structure preserved (#, -, >, links)
• Inline code, HTML tags, emojis unchanged
• do_not_translate terms unchanged
• Plurals, format strings intact

Issues are written to po/needs-review.txt.

Flags:

• --strict — all checks
• --mark-fuzzy — automatically mark problematic msgstrs as fuzzy
• --fix (if available) — attempt auto-fix

5. Build check

MDBOOK_BOOK__LANGUAGE=ru mdbook build -d book/ru

A gettext error here means po/ru.po has a syntax issue.

Hard rules

• Never edit msgid by hand — it's extracted from src/*.md
• Never edit po/messages.pot — auto-generated
• Add new terms to po/glossary.yaml to keep translation quality consistent
• All 3 languages stay in sync — if one falls behind, mdbook build falls back to source (not ideal)

Quick commands

• /sync-po — step 1
• /extract-batch <lang> <filter> <count> — step 2
• /translate <lang> [filter] — step 3
• /validate <lang> — step 4
• /fuzzy-count — show fuzzy/untranslated counts per .po file