2020-12-19 19:19:35 +00:00
# LibreTranslate
2020-12-20 20:52:02 +00:00
2020-12-20 23:56:05 +00:00
[Try it online! ](https://libretranslate.com ) | [API Docs ](https://libretranslate.com/docs )
2021-02-10 00:01:24 +00:00
[](https://pypi.org/project/libretranslate) [](https://github.com/uav4geo/LibreTranslate/actions?query=workflow%3A%22Run+tests%22) [](https://hub.docker.com/r/libretranslate/libretranslate) [](https://github.com/uav4geo/LibreTranslate/actions?query=workflow%3A%22Publish+to+GitHub+Container+Registry%22)
2020-12-29 18:13:40 +00:00
2021-01-02 17:17:11 +00:00
Free and Open Source Machine Translation API, entirely self-hosted. Unlike other APIs, it doesn't rely on proprietary providers such as Google or Azure to perform translations.
2020-12-20 20:52:02 +00:00
2020-12-20 21:04:48 +00:00
[Try it online! ](https://libretranslate.com ) | [API Docs ](https://libretranslate.com/docs )
2020-12-20 20:52:02 +00:00
2020-12-20 21:13:38 +00:00
## API Examples
Request:
```javascript
const res = await fetch("https://libretranslate.com/translate", {
method: "POST",
body: JSON.stringify({
q: "Hello!",
source: "en",
target: "es"
}),
2021-01-15 17:12:00 +00:00
headers: { "Content-Type": "application/json" }
2021-01-15 17:13:42 +00:00
});
2020-12-20 21:13:38 +00:00
console.log(await res.json());
```
Response:
```javascript
{
"translatedText": "¡Hola!"
}
```
2021-02-09 13:17:06 +00:00
## Install and Run
2020-12-20 20:52:02 +00:00
2020-12-20 21:13:38 +00:00
You can run your own API server in just a few lines of setup!
2021-02-10 00:01:24 +00:00
Make sure you have installed Python (3.8 or higher is recommended), then simply issue:
2020-12-20 20:52:02 +00:00
2021-02-09 13:17:06 +00:00
```bash
pip install libretranslate
libretranslate [args]
```
Then open a web browser to http://localhost:5000
2021-02-09 20:20:46 +00:00
If you're on Windows, we recommend you [Run with Docker ](#run-with-docker ) instead.
2021-02-09 13:17:06 +00:00
## Build and Run
If you want to make some changes to the code, you can build from source, and run the API:
2020-12-20 20:52:02 +00:00
```bash
2021-02-09 00:24:34 +00:00
git clone https://github.com/uav4geo/LibreTranslate
2020-12-20 20:52:02 +00:00
cd LibreTranslate
2021-02-09 13:17:06 +00:00
pip install -e .
libretranslate [args]
2021-02-10 16:05:23 +00:00
# Or
python main.py [args]
2020-12-20 20:52:02 +00:00
```
2020-12-20 21:13:38 +00:00
Then open a web browser to http://localhost:5000
2020-12-21 18:39:53 +00:00
### Run with Docker
2020-12-29 15:55:53 +00:00
Simply run:
```bash
docker run -ti --rm -p 5000:5000 libretranslate/libretranslate
```
Then open a web browser to http://localhost:5000
### Build with Docker
2020-12-21 18:39:53 +00:00
```bash
2021-03-11 06:23:22 +00:00
docker build [--build-arg with_models=true] -t libretranslate .
2020-12-21 18:39:53 +00:00
```
2021-03-11 06:23:22 +00:00
If you want to run the Docker image in a complete offline environment, you need to add the `--build-arg with_models=true` parameter. Then the language models get downloaded during the build process of the image. Otherwise these models get downloaded on the first run of the image/container.
2020-12-21 18:39:53 +00:00
Run the built image:
```bash
docker run -it -p 5000:5000 libretranslate [args]
```
Or build and run using `docker-compose` :
```bash
docker-compose up -d --build
```
> Feel free to change the [`docker-compose.yml`](https://github.com/uav4geo/LibreTranslate/blob/main/docker-compose.yml) file to adapt it to your deployment needs, or use an extra `docker-compose.prod.yml` file for your deployment configuration.
2020-12-20 20:52:02 +00:00
## Arguments
| Argument | Description | Default |
| ------------- | ------------------------------ | -------------------- |
| --host | Set host to bind the server to | `127.0.0.1` |
| --port | Set port to bind the server to | `5000` |
| --char-limit | Set character limit | `No limit` |
| --req-limit | Set maximum number of requests per minute per client | `No limit` |
2021-01-19 17:53:53 +00:00
| --batch-limit | Set maximum number of texts to translate in a batch request | `No limit` |
2020-12-20 20:52:02 +00:00
| --ga-id | Enable Google Analytics on the API client page by providing an ID | `No tracking` |
| --debug | Enable debug environment | `False` |
2020-12-20 23:56:46 +00:00
| --ssl | Whether to enable SSL | `False` |
2021-01-10 08:15:55 +00:00
| --frontend-language-source | Set frontend default language - source | `en` |
| --frontend-language-target | Set frontend default language - target | `es` |
2021-01-28 16:20:13 +00:00
| --frontend-timeout | Set frontend translation timeout | `500` |
2021-02-15 18:30:28 +00:00
| --offline | Run user-interface entirely offline (don't use internet CDNs) | `false` |
| --api-keys | Enable API keys database for per-user rate limits lookup | `Don't use API keys` |
2021-03-28 14:33:10 +00:00
| --load-only | Set available languages | `all from argostranslate` |
2020-12-20 20:52:02 +00:00
2021-02-15 18:30:28 +00:00
## Manage API Keys
LibreTranslate supports per-user limit quotas, e.g. you can issue API keys to users so that they can enjoy higher requests limits per minute (if you also set `--req-limit` ). By default all users are rate-limited based on `--req-limit` , but passing an optional `api_key` parameter to the REST endpoints allows a user to enjoy higher request limits.
To use API keys simply start LibreTranslate with the `--api-keys` option.
### Add New Keys
To issue a new API key with 120 requests per minute limits:
```bash
ltmanage keys add 120
```
### Remove Keys
```bash
ltmanage keys remove < api-key >
```
### View Keys
```bash
ltmanage keys
```
2020-12-20 20:52:02 +00:00
2021-02-26 14:07:02 +00:00
## Language Bindings
You can use the LibreTranslate API using the following bindings:
- Rust: https://github.com/DefunctLizard/libretranslate-rs
2021-02-27 15:27:14 +00:00
- Node.js: https://github.com/franciscop/translate
2021-03-03 14:20:19 +00:00
- .Net: https://github.com/sigaloid/LibreTranslate.Net
2021-02-26 14:07:02 +00:00
More coming soon!
2020-12-20 20:52:02 +00:00
## Roadmap
Help us by opening a pull request!
2020-12-21 19:31:50 +00:00
- [x] A docker image (thanks [@vemonet ](https://github.com/vemonet ) !)
2021-01-15 17:15:03 +00:00
- [x] Auto-detect input language (thanks [@vemonet ](https://github.com/vemonet ) !)
2021-02-15 18:30:28 +00:00
- [X] User authentication / tokens
2020-12-21 18:55:14 +00:00
- [ ] Language bindings for every computer language
2020-12-20 20:52:02 +00:00
2021-01-10 14:55:26 +00:00
## FAQ
### Can I use your API server at libretranslate.com for my application in production?
2021-02-15 18:30:28 +00:00
The API on libretranslate.com should be used for testing, personal or infrequent use. If you're going to run an application in production, please [get in touch ](https://uav4geo.com/contact ) to get an API key or discuss other options.
2021-01-10 14:55:26 +00:00
2021-02-26 16:19:02 +00:00
### Can I use this behind a reverse proxy, like Apache2?
Yes, here is an example Apache2 config that redirects a subdomain (with HTTPS certificate) to LibreTranslate running on a docker at localhost.
```
sudo docker run -ti --rm -p 127.0.0.1:5000:5000 libretranslate/libretranslate
```
You can remove `127.0.0.1` on the above command if you want to be able to access it from `domain.tld:5000` , in addition to `subdomain.domain.tld` (this can be helpful to determine if there is an issue with Apache2 or the docker container).
Add `--restart unless-stopped` if you want this docker to start on boot, unless manually stopped.
< details >
< summary > Apache config< / summary >
< br >
2021-02-26 16:24:58 +00:00
Replace [YOUR_DOMAIN] with your full domain; for example, `translate.domain.tld` or `libretranslate.domain.tld` .
2021-02-26 16:19:02 +00:00
Remove `#` on the ErrorLog and CustomLog lines to log requests.
2021-02-26 16:24:58 +00:00
2021-02-26 16:19:02 +00:00
```ApacheConf
#Libretranslate
#Redirect http to https
< VirtualHost * :80 >
ServerName http://[YOUR_DOMAIN]
Redirect / https://[YOUR_DOMAIN]
# ErrorLog ${APACHE_LOG_DIR}/error.log
# CustomLog ${APACHE_LOG_DIR}/tr-access.log combined
< / VirtualHost >
#https
< VirtualHost * :443 >
ServerName https://[YOUR_DOMAIN]
ProxyPass / http://127.0.0.1:5000/
ProxyPassReverse / http://127.0.0.1:5000/
SSLEngine on
SSLCertificateFile /etc/letsencrypt/live/[YOUR_DOMAIN]/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/[YOUR_DOMAIN]/privkey.pem
SSLCertificateChainFile /etc/letsencrypt/live/[YOUR_DOMAIN]/fullchain.pem
# ErrorLog ${APACHE_LOG_DIR}/tr-error.log
# CustomLog ${APACHE_LOG_DIR}/tr-access.log combined
< / VirtualHost >
```
Add this to an existing site config, or a new file in `/etc/apache2/sites-available/new-site.conf` and run `sudo a2ensite new-site.conf` .
2021-02-26 16:24:58 +00:00
To get a HTTPS subdomain certificate, install `certbot` (snap), run `sudo certbot certonly --manual --preferred-challenges dns` and enter your information (with `subdomain.domain.tld` as the domain). Add a DNS TXT record with your domain registrar when asked. This will save your certificate and key to `/etc/letsencrypt/live/{subdomain.domain.tld}/` . Alternatively, comment the SSL lines out if you don't want to use HTTPS.
2021-02-26 16:19:02 +00:00
< / details >
2020-12-20 20:52:02 +00:00
## Credits
This work is largely possible thanks to [Argos Translate ](https://github.com/argosopentech/argos-translate ), which powers the translation engine.
## License
2020-12-20 23:56:05 +00:00
[GNU Affero General Public License v3 ](https://www.gnu.org/licenses/agpl-3.0.en.html )
