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 & 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      # detection (optional)

Optional extras:

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 Lang Classifier Classics for detection:

ovos-translate-server \
  --tx-engine ovos-translate-plugin-nllb \
  --detect-engine ovos-lang-detector-classics-plugin

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.

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

UTCP — Universal Tool Calling Protocol

Every running instance of the server exposes a machine-readable UTCP manual at:

GET /utcp

The manual describes all translation and detection endpoints as HTTP tools so UTCP-compatible AI agents can discover and invoke them directly — no extra proxy layer required. The URLs in the manual use the same host/port the request arrived on, so the document is always self-consistent under any reverse-proxy deployment.

curl http://localhost:9686/utcp | python3 -m json.tool

Exposed tools

No extra dependency is required for UTCP; the /utcp endpoint is always registered when the server starts.

MCP — Model Context Protocol

An optional MCP server can be embedded in the main application when the mcp extra is installed and the server is started with --mcp:

pip install "ovos-translate-server[mcp]"
ovos-translate-server --tx-engine ovos-translate-plugin-nllb --mcp

Installing the extra alone does not mount /mcp — the flag is required, so that installing an extra never silently exposes a tool endpoint. With the flag passed, the MCP endpoint is mounted at /mcp using the Streamable HTTP transport. Agents that speak MCP (Claude Desktop, Continue, etc.) can add it as a server at:

http://localhost:9686/mcp

MCP tools

Standalone MCP process

If you prefer to run the MCP server as a separate process (e.g. to bind it to localhost only while the HTTP API is public):

python -m ovos_translate_server.mcp_server \
    --tx-engine ovos-translate-plugin-nllb \
    --detect-engine ovos-lang-detector-classics-plugin \
    --host 127.0.0.1 \
    --port 9687

Embedding in a custom FastAPI app

from ovos_translate_server import start_translate_server
from ovos_translate_server.mcp_server import get_mcp_app

app, engine = start_translate_server("ovos-translate-plugin-nllb", enable_mcp=True)
# MCP is already mounted at /mcp; or mount it manually at a custom path:
# app.mount("/my-mcp", get_mcp_app(engine))

Claude Desktop configuration

{
  "mcpServers": {
    "ovos-translate": {
      "url": "http://localhost:9686/mcp"
    }
  }
}

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.

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

EXPOSE 9686
ENTRYPOINT ["ovos-translate-server", \
            "--tx-engine", "ovos-translate-plugin-nllb", \
            "--detect-engine", "ovos-lang-detector-classics-plugin"]

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

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.