# Project pack: LibreTranslate @ a0ec22e

Facts about **LibreTranslate** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> LibreTranslate is a self-hosted machine translation service with a simple web page and a full API. It uses open language models, so translations happen on your own computer. You can add languages, translate files and call it from scripts and apps.

## Version and source
- Repository: https://github.com/LibreTranslate/LibreTranslate
- Pinned commit: `a0ec22ee93059b138f53fcefe1160d373547a448`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/LibreTranslate/LibreTranslate/archive/a0ec22ee93059b138f53fcefe1160d373547a448.zip
- Official docs: https://docs.libretranslate.com
- Licence: **AGPL-3.0-only**. Free to use and change. If other people use your changed version, including over a network (for example a website you host for them), you must offer them your source code under the same licence. Using it privately for yourself or your household has no extra obligations.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/LibreTranslate/LibreTranslate bespoke-libretranslate
  cd bespoke-libretranslate
  git checkout --detach a0ec22ee93059b138f53fcefe1160d373547a448
  # Prepare development requirements and local configuration first.
  python3 -m venv .venv
  . .venv/bin/activate
  pip install -e .
  libretranslate --load-only en,es,fr
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  docker run -d --name libretranslate -p 5000:5000 -v lt-local:/home/libretranslate/.local libretranslate/libretranslate --load-only en,es,fr
  # the first start downloads language models, then open http://localhost:5000
  ```

- Needs: Docker for a trial, Python 3.9 to 3.12 for development, several GB of disk for models
- Develop: `libretranslate --load-only en,es,fr`
- Test: `pytest`
- Stack: python, javascript (Flask, Argos Translate, Bootstrap). Difficulty for a non-developer with an AI: **moderate**. A compact Flask app around the Argos Translate engine. The web page and API are small; language models are large downloads.

## The project's own AI instructions
Read these in the repository before changing code: `AGENTS.md`.

## Customisation points (settings → extend → code)
- **languages** [settings]: Which languages to offer, to save memory. → `--load-only option or LT_LOAD_ONLY`
- **api-keys-and-limits** [settings]: Who can use it and how often. → `LT_API_KEYS and --req-limit options`
- **web-ui** [extend]: Wording, logo and colours of the page. → `libretranslate/templates and libretranslate/static`
- **api-clients** [extend]: Translate from scripts, browsers and apps. → `/docs API and the libretranslate client libraries`
- **app-code** [code]: New endpoints and options. → `libretranslate/app.py and libretranslate/`

## Must keep working
- Request limits and API-key checks.
- File translation safety limits.
- Model loading, since mistakes can cause large memory use.

## Staying updatable
Prefer options and the API. For UI changes, edit templates and static files only, to keep merging easy.

## Data, costs and safety
- Personal data: **no**. Stored in: Language models under the user's local data folder and an optional SQLite file for API keys. Translated text is not stored by default. Use your own server for private text.
- Setting `LT_API_KEYS` (**secret**: the person enters it themselves, never in chat): Set to true to require API keys for requests.
- Setting `LT_LOAD_ONLY`: Comma-separated language codes to load, to save memory.
- Language models are large. Check disk and memory before loading many.
- If you expose it publicly, enable API keys and rate limits.

---

# Customising LibreTranslate

LibreTranslate is a small Flask app. Most changes are options, templates and API usage.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Flask app and API | libretranslate/app.py and libretranslate/ |
| Web page | libretranslate/templates/ and libretranslate/static/ |
| Translations of the interface | libretranslate/locales/ |
| Database for API keys | libretranslate/api_keys.py |
| Docker | Dockerfile, docker-compose.yml, docker-compose.cuda.yml |
| Tests | libretranslate/tests/ |

## Use the gentlest change first

1. **Settings (no code):** languages, API keys and rate limits.
2. **Extend:** API scripts and web page styling.
3. **Code:** endpoints and options.

## Recipes

- **Call the API:** POST to `/translate` with `q`, `source`, `target` and `format`.
- **Subtitle translator:** read the `.srt` file, translate only text lines through the API, and write it back with the same timings.

## Running and checking your changes

- Start the server, open the web page and translate a sentence each way.
- `pytest` for the area you changed.
- Check memory use with only the languages you need loaded.

## Pitfalls

- Don't load all languages on a small server.
- Model downloads can take a long time on first start.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/libretranslate/a0ec22e/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/libretranslate/a0ec22e/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/libretranslate/a0ec22e/r2/SKILL.md)