NOHCHO — Chechen MT + TTS Toolkit

Нохчийн мотт (Chechen) machine translation and speech synthesis — development and evaluation toolkit.

Chechen is a critically under-resourced language (~1.5 M speakers). This toolkit provides:

• Translation — pluggable providers (Google Translate baseline; NLLB fine-tune seam)
• TTS — Meta MMS facebook/mms-tts-che baseline → VITS/XTTS fine-tune path
• Eval harness — chrF + BLEU metrics on a shared held-out corpus, JSON reports
• Data catalogue — vetted public sources with license notes

The architecture uses a provider-abstraction (Protocol) so cloud APIs and local models are swapped without rewriting evaluation or CLI code.

---

Architecture

src/nohcho/
├── languages.py        language registry: internal code (che/rus/eng) → provider codes
├── config.py           settings from .env (pydantic-settings)
├── translate/
│   ├── base.py             TranslationProvider Protocol + result types
│   ├── google_provider.py  Google Cloud Translate (supports che)
│   ├── nllb_provider.py    local NLLB — fine-tune seam (base model has NO Chechen)
│   └── registry.py
├── tts/
│   ├── base.py             TTSProvider Protocol
│   ├── mms_provider.py     Meta MMS-TTS (facebook/mms-tts-che) — open baseline
│   └── registry.py
├── eval/               BLEU/chrF metrics + audio sanity + runner
├── data/               parallel corpus loader + public source catalogue
└── cli.py              CLI entry point: nohcho

Key language facts (2026):

• Google Translate supports Chechen (ce). Open NLLB-200 does not — nllb_provider.py is the explicit fine-tune extension point.
• Meta MMS provides an open VITS checkpoint facebook/mms-tts-che — our speech baseline.
• Best available parallel corpus: nmd-ce-ru-171k-v0 (171k rows, MIT).

---

Installation

python -m venv .venv && source .venv/bin/activate   # Linux/macOS
# Windows: .\.venv\Scripts\Activate.ps1

pip install -e ".[google,local,dev]"   # all extras; pick only what you need
cp .env.example .env                   # fill in keys

Extras:

• google — Google Cloud Translate API
• local — transformers + torch for MMS-TTS and NLLB (heavy, ~2 GB download)
• dev — pytest, ruff

---

Usage

nohcho languages                                   # show language codes per provider
nohcho sources                                     # list vetted public datasets

# Translation (requires GOOGLE_APPLICATION_CREDENTIALS)
nohcho translate "Маршалла хуьлда" --from che --to rus
nohcho translate "Hello" --from eng --to che

# TTS (requires extra [local]; first run downloads ~300 MB from HuggingFace)
nohcho speak "Маршалла хуьлда шуьга" --lang che --out outputs/hello.wav

# Evaluate translation on a parallel corpus → BLEU + chrF + JSON report
nohcho eval-translate data/eval/sample_che_ru.tsv --from che --to rus

---

Data

Put parallel corpora in data/parallel/ (UTF-8 TSV: <che>\t<ru>), audio in data/audio/, held-out eval in data/eval/.

Real data is not committed (.gitignore) — version manifests instead. Run nohcho sources for a curated list of public sources with license notes.

---

Metrics

• Translation: chrF is the primary signal — character-level, robust on morphologically rich low-resource languages; BLEU is secondary.
• TTS: automated metrics (eval/tts_metrics.py) catch only hard failures (silence, clipping, unrealistic duration). Quality requires native-speaker MOS evaluation.

---

Running tests

pytest           # fast unit tests (no heavy models)
ruff check src   # lint

---

Roadmap

Phase	Status	Goal
1 — Scaffold	✅ Done	Provider abstraction, CLI, eval harness, baselines
2 — Corpus	Planned	Collect & clean che-ru corpus; held-out eval split
3 — Baseline	Planned	Google Translate + MMS-TTS scores; native-speaker MOS
4 — Fine-tune	Planned	NLLB + Chechen token; VITS/XTTS on audio
5 — Compare	Planned	A/B fine-tune vs baseline via eval harness
6 — Web/API	Planned	Wrap CLI core in REST API

See .planning/ROADMAP.md for detailed requirements per phase.

---

Contributing

Contributions welcome — especially:

• Native speaker data — che-ru sentence pairs, audio recordings
• New providers — any MT or TTS engine that supports Chechen
• Corpus cleaning scripts — Unicode NFC, length-ratio filters, dedup
• Evaluation — MOS testing, human evaluation setups

See CONTRIBUTING.md for details.

---

License

MIT — see LICENSE.

Data sources have their own licenses — see nohcho sources or data/LICENSES.md.

---

Why "NOHCHO"?

Нохчо (Noxçо) — the Chechen self-designation. The people call themselves Noxçо; their language is Нохчийн мотт (Noxçiyn mott).