June 16, 2026 5 min read Python fork

LibreTranslate

Abstract

Free and Open Source Machine Translation API. Self-hosted, offline capable and easy to setup.

Forked from LibreTranslate/LibreTranslate

The Problem

Organizations that need a self‑hosted, offline‑capable translation service often encounter code that is hard to maintain, lacks reproducible builds, and exposes a wildcard CORS policy. These friction points increase operational risk and slow down secure deployments.

What This Does

LibreTranslate is a free, open‑source Machine Translation API powered by the Argos Translate library. The repository contains 214 files organised into two projects: libretranslate/ (172 files) and scripts/ (8 files). Core translation logic lives in libretranslate/app.py (the primary API handler), while supporting modules such as storage.py, api_keys.py, cache.py, secret.py, detect.py, language.py, and locales.py provide backend services, key management, caching, language detection, and i18n handling.

Execution starts at the main entry point in libretranslate/main.py:268, which calls create_app to initialise the framework (Flask/Django/Express‑style) and then runs the server. The translation pipeline flows through translate → iso2model → language‑model lookup, with get_storage (called from 12 places) and get_req_api_key (called from 5 places) as the most‑touched functions. A secondary entry point spec at libretranslate/app.py:1330 generates the OpenAPI specification, reaching 22 functions.

The internal call graph resolves 164 self‑call edges; notable hubs are get_storage (12 callers), get_str (6 callers), and get_json_dict (5 callers). Three modules (libretranslate/__init__.py, libretranslate/main.py, libretranslate/app.py) participate in a circular import dependency, and app.py contains 1171 lines of code, creating high cognitive load and deep nesting (max indentation depth 8).

How It Is Wired

Entry points: main (libretranslate/main.py:268) reaches 24 functions; spec (libretranslate/app.py:1330) reaches 22 functions; translate_file (libretranslate/app.py:883) reaches 16 functions.
Outbound effects: 16 functions make network calls (e.g., spec → lazy_swag → swag_eval → func → lookup via requests.post). File system touches occur via main → create_app [os.mkdir], translate_file → get_upload_dir [os.mkdir], and database reads/writes are performed by api_keys.py (reads/writes a DB) and cache.py (cryptographic secret generation).
Responsibility map (functions per file, callers, and effects):
libretranslate/app.py – 43 functions, called from 4 files, calls into 10, reads/writes files, defines get_version, get_upload_dir, get_req_api_key, get_req_secret, get_json_dict.
libretranslate/storage.py – 43 functions/3 types, called from 5 files, defines get_storage, exists, set_bool, get_bool, set_int.
libretranslate/api_keys.py – 7 functions/2 types, called from 2 files, reads/writes files and a DB, makes an outbound network call for key lookup.
libretranslate/cache.py – 6 functions/1 class, called from 2 files, performs a cryptographic secret‑generating operation.
libretranslate/secret.py – 14 functions, called from 2 files, defines to_base, obfuscate, generate_secret, rotate_secrets, secret_match.
libretranslate/detect.py – 6 functions/2 classes, called from 2 files.
libretranslate/language.py – 7 functions, called from 2 files, defines iso2model, model2iso, load_languages, load_lang_codes, get_language_with_fallback.
libretranslate/main.py – 4 functions, called from 2 files, defines get_parser, get_args, main, redirect.
libretranslate/locales.py – 7 functions, called from 1 file.
Module graph: libretranslate/app imports from libretranslate/__init__ and libretranslate/main; libretranslate/main imports from libretranslate/app, creating a cycle that inflates instability (instability 0.7 for app, 0.29 for __init__ and main).

How To Use It

Setup

Install the Python package: pip install -e . (pyproject.toml present).
Or build and run via Docker: docker compose up -d (docker‑compose.yml and docker/Dockerfile exist).

Configuration

The API reads environment variables and a .env‑style config; see libretranslate/app.py for the exact variables it references (e.g., LIBRETRANSLATE_SECRET, LIBRETRANSLATE_API_KEY).
CORS is currently set to "*" in libretranslate/app.py – replace with an explicit allow list for production.

Running it

Start the server from the CLI: python -m libretranslate.main (entry point main.py:268).
For HTTPS behind a reverse proxy, use the provided Docker Compose files or the k8s.yaml manifest.

Real‑World Use

A CI pipeline fetches translated subtitles for a multilingual video platform. The backend calls POST /translate with { "q": "text", "source": "en", "target": "fr" }. The request is authenticated via an API key stored in api_keys.py, routed through storage.py for request‑rate limits, and cached by cache.py to avoid repeated model loads. If the key is missing, api_keys.lookup returns a 401, and the caller retries with a fallback key.

import requests
resp = requests.post(
    "http://localhost:5000/translate",
    json={"q": "Hello world", "source": "en", "target": "es"},
    headers={"X-Api-Key": "my-secret-key"}
)
print(resp.json()["translatedText"])

Code Health & Issues

High: Pin third‑party GitHub Actions to commit SHAs – .github/workflows currently uses @v2, @v4 tags for pierotofy/issuewhiz, docker/setup-qemu-action, docker/setup-buildx-action, docker/login-action; a tag can move and bring new code with secrets.
High: Commit a lockfile beside pyproject.toml – no lockfile is present, so transitive dependencies may differ between test and production builds.
High: Replace the wildcard CORS origin with an explicit allow list – libretranslate/app.py sets Access-Control-Allow-Origin: *"; pairing with credentials is disallowed by browsers.
Medium: Declare least‑privilege permissions for GITHUB_TOKEN – 3 workflows have no permissions block; add contents: read at the top and widen per job.
Medium: Enable Dependabot or Renovate – no update bot configured; add .github/dependabot.yml for Python and GitHub‑Actions ecosystems.
Medium: Pin container base image by digest – docker/Dockerfile uses python:3.11.14-slim-bookworm without a digest; pin via python:3.11.14-slim-bookworm@sha256<digest> and enable Dependabot Docker monitoring.
Medium: Gate pull requests on a dependency vulnerability scan – CI lacks dependency review; add dependency-review-action on pull_request or osv-scanner on push.
Medium: Set persist-credentials: false on checkout – publish-package.yml keeps the token; add with: persist-credentials: false and pass explicit tokens only to the push step.
Low: Set timeout-minutes on workflow jobs – 4 jobs have no timeout; add realistic bounds to prevent overlapping runs.

The Bottom Line

LibreTranslate delivers a capable, self‑hosted translation API with solid i18n support and Docker/Kubernetes deployment options. However, the codebase suffers from circular imports, an oversized app.py, missing dependency lockfile, and a permissive CORS policy that together raise operational risk. Teams comfortable with Docker and willing to tighten security posture (pin actions, add lockfile, restrict CORS) can operate it safely; others may need to invest in refactoring the import graph and cleaning up CI configuration before production use.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

214 files

JSON61
Python39
YAML9
Markdown5
Docker4
CSS4

DjangoFlaskExpressDockerKubernetes

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["libretranslate<br/>32 modules"] g1["scripts<br/>7 modules"] g2["(root)<br/>3 modules"] g1 -->|9| g0 g2 -->|3| g0

Module dependencies

The 10 most depended-upon modules of 42, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_libretranslate___init__["__init__"] n1_libretranslate_main["main"] n2_libretranslate_app["app"] n3_libretranslate_init["init"] n4_libretranslate_language["language"] n5_ibretranslate_default_values["default_values"] n6_libretranslate_locales["locales"] n7_libretranslate_storage["storage"] n8_libretranslate_api_keys["api_keys"] n9_libretranslate_manage["manage"] n0_libretranslate___init__ --> n1_libretranslate_main n0_libretranslate___init__ --> n9_libretranslate_manage n8_libretranslate_api_keys --> n5_ibretranslate_default_values n2_libretranslate_app --> n0_libretranslate___init__ n2_libretranslate_app --> n4_libretranslate_language n2_libretranslate_app --> n6_libretranslate_locales n2_libretranslate_app --> n8_libretranslate_api_keys n2_libretranslate_app --> n3_libretranslate_init n3_libretranslate_init --> n4_libretranslate_language n1_libretranslate_main --> n2_libretranslate_app n1_libretranslate_main --> n5_ibretranslate_default_values n9_libretranslate_manage --> n8_libretranslate_api_keys n9_libretranslate_manage --> n5_ibretranslate_default_values classDef cyc stroke:#ef4444,stroke-width:2px; class n0_libretranslate___init__,n1_libretranslate_main,n2_libretranslate_app cyc;

Dependencies

8 of 21 declared dependencies are a major version behind. Resolved 21 of 21 against the registry.

Package	Declared	Latest	Behind
`redis`	==4.4.4	8.1.0	4 major
`packaging`	==23.1	26.3	3 major
`flask-limiter`	==2.6.3	4.1.1	2 major
`flask`	==2.2.5	3.1.3	1 major
`flask-swagger-ui`	==4.11.1	5.32.14	1 major
`flask-babel`	==3.1.0	4.0.0	1 major
`waitress`	==2.1.2	3.0.2	1 major
`werkzeug`	==2.3.8	3.1.8	1 major

Findings

LowDependencies declared without a lockfile - non-reproducible builds pyproject.toml

Open in Code Brain → See its neighbourhood →

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high3

medium5

low1

Pin third-party GitHub Actions to a commit SHAhigh8 occurrences

.github/workflows

pierotofy/issuewhiz@v2, docker/setup-qemu-action@v4, docker/setup-buildx-action@v4, docker/login-action@v4

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Commit a lockfile beside the manifesthigh

pyproject.toml

manifest with no lockfile in scope

An unlocked range means the artifact you tested and the artifact you ship can contain different transitive code, so a malicious patch release reaches production with no diff.

Fix: Run the package manager once and commit the generated lockfile.

Replace the wildcard CORS origin with an explicit allow listhigh

libretranslate/app.py

Access-Control-Allow-Origin", "*"

Any page on the internet can call the API with the browser's cookies attached, so a logged-in visitor to an unrelated site performs authenticated requests without knowing, and the wildcard combined with credentials is the exact configuration browsers refuse for that reason.

Fix: List the origins the API actually serves, and never pair a wildcard with credentials.

Declare least-privilege permissions for GITHUB_TOKENmedium3 occurrences

.github/workflows/publish-docker.yml

3 workflow(s) declare no permissions, 2 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

1 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium2 occurrences

docker/Dockerfile

python:3.11.14-slim-bookworm, python:3.11.14-slim-bookworm

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/publish-package.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow4 occurrences

.github/workflows/issue-triage.yml

4 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.

View on GitHub All Projects