| 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.potmsgmerge → 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
