This release is a pre-release and may not be stable for production use.
Interpres — Translator
Translate text and files between languages using Hugging Face translation models (default: Meta NLLB).
Interpres (Translator) is a lightweight CLI and Python package for fast, batch-friendly translation workflows. It supports single-sentence translation, directory and file translation, and robust PO (gettext) file handling for localization workflows.
Key features
- CLI + Python API
- Default model:
facebook/nllb-200-distilled-600M(configurable) - Fast batch translation with configurable batch size, epochs, and parallelism
- Full support for PO files: preserves metadata, comments, and structure; translates only untranslated entries by default; force retranslate option
- Language list compatible with NLLB (200+ languages)
Quick install
pip:
pip install interpres
Install from source:
pip install git+https://github.com/wasertech/Translator.git
Specify a release:
pip install interpres==0.3.1b4
pip install git+https://github.com/wasertech/Translator.git@v0.3.1b4
CLI overview
Run:
translate [FROM] [TO] [SENTENCES...]
Basic examples:
# Single sentence
translate en fr "This is a test."
# Interactive shell
translate
# or get help
translate --help
# Translate a directory and save output
translate --directory ./texts --save translations.txt eng_Latn fra_Latn
Important options (common)
- -m, --model_id MODEL_ID : Hugging Face model ID to use
- -d, --directory DIRECTORY : Translate files in a directory
- --po : Translate PO files (gettext)
- --force : Force retranslation (including already translated entries)
- -b, --batch_size : Batch size for model inference
- -e, --nepoch : Number of epoch splits used to pipeline batches (tweak to avoid OOM)
- -n, --nproc : Number of CPU workers for preprocessing/filtering
- -L, --language_list : Show supported languages
PO-file translation (high level)
- Finds .po files recursively and validates Language metadata
- By default translates empty msgstr entries only
- --force reprocesses every entry
- Preserves comments, headers, and file formatting — ideal for Poedit/Django workflows
Python API (simple)
from translator import Translator
t = Translator("eng_Latn", "fra_Latn")
out = t.translate("This is a simple sentence.")
print(out)
PO-file example (Python)
from translator import Translator, utils
translator = Translator("eng_Latn", "spa_Latn")
po = utils.read_po_file("messages.po")
if utils.should_translate_po_file(po, "eng_Latn"):
entries = utils.extract_untranslated_from_po(po)
translations = translator.translate(entries)
mapping = dict(zip(entries, translations))
utils.update_po_with_translations(po, mapping, force=False)
utils.save_po_file(po, "messages.po")
Language support
Depending on models used, you might get fewer choices
but with NLLB you get more than 200 most popular ones.
# translate -L
❯ translate --language_list
Language list:
...
From python:
>>> import translator
>>> len(translator.LANGS)
202
>>> translator.LANGS
['ace_Arab', '...', 'zul_Latn']
>>> from translator.language import get_nllb_lang, get_sys_lang_format
>>> nllb_lang = get_nllb_lang("en")
>>> nllb_lang
'eng_Latn'
>>> get_sys_lang_format()
'fra_Latn'
Checkout LANGS to see the full list of supported languages.
Custom models
- Use any Hugging Face translation model compatible with the Transformers pipeline:
translate --model_id "HUGGINGFACE/MODEL_ID" ... - Prefer models that match your language pair and domain. Models trained or fine-tuned specifically for a given language pair (e.g., en→fr) often produce noticeably better results than general multilingual models.
- Domain/context-specific models are best: if you're translating a website, a model trained on website or localization data (or fine-tuned on your site's content) will usually yield more accurate, consistent, and context-aware translations than the default general-purpose model.
Performance tips
- Set nepoch (-e) and batch_size (-b) to fit your device memory. Bigger batch_size speeds throughput but uses more memory.
- Use -n to match your CPU threads for preprocessing speed.
- Use custom models: choosing a language-pair-specific or domain-specific model (or fine-tuning one on your data) often improves translation quality and consistency, especially for specialized content such as legal texts, technical docs, or websites.
License
Mozilla Public License 2.0 — see LICENSE
Using this tool to translate a sentence, the licence of the original sentence still applies unless specified otherwise.
Meaning, if you translate a sentence under Creative Commons CC0, the translation is also under Creative Commons CC0.
Idem for any licence.
Contribute & sponsor
- Share and talk about translations models you like to use and tell us why.
- Open issues or PRs for features, bugfixes, or performance improvements.
- Sponsor this project
Thanks for building with Interpres — translate confidently, scale thoughtfully.
Metadata
Release files for interpres 0.4.0b6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| interpres-0.4.0b6.tar.gz | 24.0 kB | Without provenance | Details for interpres-0.4.0b6.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| interpres-0.4.0b6-py3-none-any.whl | Python 3 | none | any | Details for interpres-0.4.0b6-py3-none-any.whl |
Total release size: 48.5 kB
Release files / interpres-0.4.0b6.tar.gz
| Download URL | interpres-0.4.0b6.tar.gz |
|---|---|
| Size | 24.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
12985ae0c1dd11901a623afbd6378bd03d7a72f755217e2ff9e00ec32ee46029
|
|
BLAKE2b-256 checksum How to use checksums |
3d6968c7f7be1615ca53035a3df5e2899607aa70ddbb1be1ddd429aefe75a3cc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Release files / interpres-0.4.0b6-py3-none-any.whl
| Download URL | interpres-0.4.0b6-py3-none-any.whl |
|---|---|
| Size | 24.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
30b6b55c1e77d0b26960f2e3b7ac73a4ebd0fe82eb150888a9fcba83792f51e7
|
|
BLAKE2b-256 checksum How to use checksums |
1b94f20ff97267a116951e5369247b29aa9a300d63cb6a8354090112427f8d49
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Security for interpres 0.4.0b6
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.