A translation service for web-novel metadata (titles, author, synopsis, tags) and HTML chapter content — markup preserved, only human-readable text translated. Run it as a standalone container or embed it as a Python library inside your own app.

Built as the stateless translation engine behind lightnovel-crawler, with switchable engines (free-tier hosted APIs and CPU-friendly local models). Every request can carry a per-novel glossary that gets injected into translations and returned with any new terms — so the caller keeps names and terms consistent across thousands of chapters.

✨ Highlights

🚀 Quick start

No config file needed — a curated set of free providers is pre-wired, and the keyless Bing lane is the default, so translation works even with zero keys:

docker compose up -d
curl http://localhost:8184/health   # shows which engines came up

Then open http://localhost:8184/ and paste your provider API keys — the matching engines enable instantly, no restart needed.

📚 See the deployment guide for engine keys, the keyless Bing lane, and API examples · design doc for API & architecture · engine research.

🔌 API

⚠️ The API is unauthenticated by design — run it on localhost or a private network only (see the deployment guide).

📦 Use as a library

pip install lncrawl-translator   # Python 3.9+

The embedded service is a thread-safe, synchronous facade that runs the same engine router on its own event loop:

from translator import TranslatorService

service = TranslatorService(config_path="translator.yml")

service.detect(["どこから来ましたか"])                 # local, no quota
response = service.translate_text({
    "texts": ["少年は勇者になった"],
    "target_lang": "en",
    "glossary": {"勇者": "Hero"},
})
print(response.translations, response.engine, response.new_terms)

service.close()  # on shutdown

translate_text / translate_html accept an optional signal (threading.Event) for cooperative cancellation and a timeout in seconds.

Error handling. Failures share a common TranslatorError base, re-exported from the top-level namespace — map them without importing pydantic or reaching into internals:

from translator import TranslatorError, ApiError, AbortedError, InvalidRequestError

Invalid dict payloads raise InvalidRequestError (not pydantic's ValidationError). Need only a language code? from translator import detect_code returns the bare ISO 639-1 code (or None) without ever constructing a service; detect_language is also available.

Mount the dashboard into a host app

app.mount("/translator", service.create_app())

The mounted app shares the service's live config — edits in the dashboard apply to the embedded service immediately. It carries no authentication of its own; the host gates access.

When the host authenticates the mount, pass create_app(auth=True): the OpenAPI then declares HTTPBasic and HTTPBearer schemes (so the docs' Authorize button works), and the dashboard reads an admin token from the page's URL fragment (#token=…) and sends it as a Bearer header. The schemes are only declared here — the host still verifies the credential.

🛠️ Development

uv sync
uv run poe check      # ruff + mypy + pytest
uv run poe dev        # dev server with auto-reload
uv run poe start      # production-style server (uvicorn on :8184)
uv run poe live-test  # smoke-test real engines from config.yml (opt-in)

See AGENTS.md for project decisions and conventions, and CHANGELOG.md for release notes.

📜 License

Licensed under the Apache License 2.0.