Metadata-Version: 2.4
Name: ovos-translate-server
Version: 0.11.3a5
Summary: FastAPI server to host OpenVoiceOS translate plugins as a service
Author-email: JarbasAi <jarbasai@mailfence.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/OpenVoiceOS/ovos-translate-server
Project-URL: Repository, https://github.com/OpenVoiceOS/ovos-translate-server
Keywords: plugin,lang,detect,translate,OVOS,OpenVoiceOS
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: fastapi>=0.115
Requires-Dist: uvicorn[standard]>=0.34
Requires-Dist: ovos-plugin-manager
Requires-Dist: python-multipart
Provides-Extra: lang-names
Requires-Dist: langcodes; extra == "lang-names"
Provides-Extra: mcp
Requires-Dist: fastmcp>=4.1.1; extra == "mcp"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: httpx<1; extra == "test"
Requires-Dist: httpx2; extra == "test"
Requires-Dist: python-multipart; extra == "test"
Requires-Dist: uvicorn; extra == "test"
Requires-Dist: deepl; extra == "test"
Requires-Dist: google-cloud-translate; extra == "test"
Requires-Dist: azure-ai-translation-text<2; extra == "test"
Requires-Dist: boto3; extra == "test"
Requires-Dist: libretranslatepy; extra == "test"
Requires-Dist: deeplx-tr; extra == "test"
Requires-Dist: marshmallow<4; extra == "test"
Requires-Dist: mcp>=2.3.0; extra == "test"
Requires-Dist: utcp>=1.2.0; extra == "test"
Requires-Dist: utcp-http>=1.1.14; extra == "test"
Dynamic: license-file

# OpenVoiceOS Translate Server

Turn any OVOS language plugin into an HTTP microservice for translation and
language detection.

Pair it with the [companion client plugin](https://github.com/OpenVoiceOS/ovos-translate-server-plugin)
to offload translation from an OVOS device, or point existing tooling at the
[vendor-compatible endpoints](#vendor-compatible-endpoints) below.

## Contents

- [Install](#install)
- [Usage](#usage)
- [HTTP API](#http-api)
- [AI agent integration](#ai-agent-integration): UTCP and MCP
- [Vendor-compatible endpoints](#vendor-compatible-endpoints)
- [Docker](#docker)
- [Documentation](#documentation)
- [Examples](#examples)
- [Credits](#credits)

## Install

```bash
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:

```bash
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](docs/ai-agents.md) |
| `lang-names` | `pip install "ovos-translate-server[lang-names]"` | human-readable language names in vendor `languages` responses |

## Usage

```bash
$ 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](https://github.com/OpenVoiceOS/ovos-translate-plugin-nllb)
for translation and the `langdetect` detector from
[Lang Classifier Classics](https://github.com/OpenVoiceOS/ovos-lang-detector-classics-plugin)
for detection:

```bash
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](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 |

```bash
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](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](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/`](examples/). Full endpoint
reference, curl examples, and client-configuration snippets:
[docs/api-compatibility.md](docs/api-compatibility.md).

```bash
# 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:

```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:

```bash
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](docs/index.md) | Overview, installation, native HTTP API, plugin interface |
| [docs/ai-agents.md](docs/ai-agents.md) | MCP and UTCP: agent recipes, tool reference, deployment |
| [docs/api-compatibility.md](docs/api-compatibility.md) | Vendor routers — prefixes, endpoints, curl, client configuration |
| [docs/language-codes.md](docs/language-codes.md) | Per-vendor language-code normalisation |
| [docs/detection.md](docs/detection.md) | Language-detection priority and per-router behaviour |

## Examples

[`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](examples/README.md).

## Credits

Developed by [TigreGótico](https://tigregotico.pt) for
[OpenVoiceOS](https://openvoiceos.org).

[![NGI0 Commons Fund](./ngi.png)](https://nlnet.nl/project/OpenVoiceOS)

This project was funded through the [NGI0 Commons Fund](https://nlnet.nl/commonsfund),
a fund established by [NLnet](https://nlnet.nl) with financial support from the
European Commission's [Next Generation Internet](https://ngi.eu) programme, under
the aegis of [DG Communications Networks, Content and Technology](https://commission.europa.eu/about-european-commission/departments-and-executive-agencies/communications-networks-content-and-technology_en)
under grant agreement No [101135429](https://cordis.europa.eu/project/id/101135429).
