This release is a pre-release and may not be stable for production use.
OpenVoiceOS Translate Server
Turn any OVOS language plugin into an HTTP microservice for translation and language detection.
Pair it with the companion client plugin to offload translation from an OVOS device, or point existing tooling at the vendor-compatible endpoints below.
Contents
- Install
- Usage
- HTTP API
- AI agent integration: UTCP and MCP
- Vendor-compatible endpoints
- Docker
- Documentation
- Examples
- Credits
Install
pip install ovos-translate-server
The server only hosts plugins — install at least one translation plugin, and optionally a dedicated language-detection plugin, alongside it:
pip install ovos-translate-plugin-nllb # translation
pip install ovos-lang-detector-classics-plugin langdetect # detection (optional)
Optional extras:
| Extra | Installs | Enables |
|---|---|---|
mcp |
pip install "ovos-translate-server[mcp]" + --mcp flag |
embedded MCP server at /mcp, see docs/ai-agents.md |
lang-names |
pip install "ovos-translate-server[lang-names]" |
human-readable language names in vendor languages responses |
Usage
$ ovos-translate-server --help
usage: ovos-translate-server [-h] --tx-engine TX_ENGINE
[--detect-engine DETECT_ENGINE]
[--host HOST] [--port PORT]
Run the OVOS Translate HTTP server.
options:
-h, --help show this help message and exit
--tx-engine TX_ENGINE
OPM translation plugin entry-point name (required)
--detect-engine DETECT_ENGINE
OPM language-detection plugin entry-point name (optional)
--host HOST host to bind (default: 0.0.0.0)
--port PORT TCP port (default: 9686)
For example, to serve the NLLB plugin
for translation and the langdetect detector from
Lang Classifier Classics
for detection:
ovos-translate-server \
--tx-engine ovos-translate-plugin-nllb \
--detect-engine ovos-lang-detector-plugin-langdetect
When --detect-engine is omitted, detection falls back to the translation
plugin's own detect() method. See docs/detection.md.
HTTP API
The native API is unauthenticated and uses GET requests. The text to
translate or detect is the last path segment and should be URL-encoded.
| Method & path | Purpose |
|---|---|
GET /status |
Plugin name and supported languages |
GET /translate/{target}/{text} |
Translate, auto-detecting the source language |
GET /translate/{source}/{target}/{text} |
Translate with an explicit source language |
GET /detect/{text} |
Detect the language, returns a BCP-47 code |
GET /classify/{text} |
Per-language confidence scores |
curl http://localhost:9686/translate/en/o%20meu%20nome%20%C3%A9%20Casimiro
# "my name is Casimiro"
curl http://localhost:9686/detect/o%20meu%20nome%20%C3%A9%20Casimiro
# "pt"
Full reference: docs/index.md.
AI agent integration
The server speaks two agent protocols. GET /utcp serves a UTCP manual and
needs nothing extra. An MCP server at /mcp needs the mcp extra and the
--mcp flag. Claude Code, Claude Desktop, OVOS personas and generic UTCP or
MCP clients can then translate text and detect languages.
The recipes, the tool reference and the deployment notes are in docs/ai-agents.md.
Vendor-compatible endpoints
The server mounts compat routers under per-vendor prefixes so existing tools, SDKs, and scripts that already target a commercial translation API can be pointed at your local OVOS instance with zero code changes — typically just a base-URL / endpoint override, exactly what a DNS redirect to the server would achieve.
| Vendor | Prefix | Key endpoints | Client |
|---|---|---|---|
| DeepL | /deepl |
POST /deepl/v2/translate |
official deepl SDK |
| DeepLX | /deeplx |
POST /deeplx/translate |
community deeplx-tr / HTTP |
| LibreTranslate | /libretranslate |
POST /libretranslate/translate, /detect, GET /libretranslate/languages |
official libretranslatepy |
| Lingva Translate | /lingva |
GET /lingva/api/v1/{source}/{target}/{query} |
HTTP (no SDK) |
| Google Cloud Translation | /google |
POST /google/language/translate/v2 |
official google-cloud-translate |
| Azure Translator | /azure |
POST /azure/translate |
official azure-ai-translation-text<2 |
| Amazon Translate | /amazon |
POST /amazon/translate/text |
official boto3 |
A runnable script for each lives in examples/. Full endpoint
reference, curl examples, and client-configuration snippets:
docs/api-compatibility.md.
# DeepLX — simple {text, source_lang, target_lang} -> {code, data}
curl -s http://localhost:9686/deeplx/translate \
-H "Content-Type: application/json" \
-d '{"text": "hello", "source_lang": "EN", "target_lang": "DE"}'
# Lingva — GET path params; use "auto" to auto-detect the source
curl -s "http://localhost:9686/lingva/api/v1/en/de/hello%20world"
Docker
Any plugin can be served with a small Dockerfile:
FROM python:3.11-slim
RUN pip install --no-cache-dir \
ovos-translate-server \
ovos-translate-plugin-nllb \
ovos-lang-detector-classics-plugin \
langdetect
EXPOSE 9686
ENTRYPOINT ["ovos-translate-server", \
"--tx-engine", "ovos-translate-plugin-nllb", \
"--detect-engine", "ovos-lang-detector-plugin-langdetect"]
Build and run:
docker build -t my-translate-server .
docker run -p 9686:9686 my-translate-server
Each plugin can ship its own Dockerfile in its repository using
ovos-translate-server as the base.
Documentation
| Document | Covers |
|---|---|
| docs/index.md | Overview, installation, native HTTP API, plugin interface |
| docs/ai-agents.md | MCP and UTCP: agent recipes, tool reference, deployment |
| docs/api-compatibility.md | Vendor routers — prefixes, endpoints, curl, client configuration |
| docs/language-codes.md | Per-vendor language-code normalisation |
| docs/detection.md | Language-detection priority and per-router behaviour |
Examples
examples/ holds one runnable script per vendor router (driving
each vendor's real client SDK where one exists) plus a native-API script. See
examples/README.md.
Credits
Developed by TigreGótico for OpenVoiceOS.
This project was funded through the NGI0 Commons Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet programme, under the aegis of DG Communications Networks, Content and Technology under grant agreement No 101135429.
2 maintainers
Metadata
2 maintainers
Release files for ovos-translate-server 0.11.3a5
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 | |
|---|---|---|---|---|
| ovos_translate_server-0.11.3a5.tar.gz | 28.3 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ovos_translate_server-0.11.3a5-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 58.8 kB
Release files / ovos_translate_server-0.11.3a5.tar.gz
| Download URL | ovos_translate_server-0.11.3a5.tar.gz |
|---|---|
| Size | 28.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
70186576a33216792b8b943c2a173aa72a37caa21c0e49d684050cef585db138
|
|
BLAKE2b-256 checksum How to use checksums |
69f46789179306bafe7b78312a133c054db67f238b9e3befaba633311b617dde
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / ovos_translate_server-0.11.3a5-py3-none-any.whl
| Download URL | ovos_translate_server-0.11.3a5-py3-none-any.whl |
|---|---|
| Size | 30.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
711ef40d6e4c56be4796d19ee2b33577a48a37aa431b0c241ca417c32be861ce
|
|
BLAKE2b-256 checksum How to use checksums |
483bc338d53dbaecfd80350016d33d6377ca826157536961afe3d841b10022c6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for ovos-translate-server 0.11.3a5
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.
