### Self-Hosted Quickstart

Source: https://docs.libretranslate.com/index

Installs LibreTranslate using pip, starts the local server, and demonstrates a translation request using curl. Includes the expected JSON response.

```bash
pip install libretranslate
libretranslate

curl -X POST http://localhost:5000/translate -d q="Hello" -d source=en -d target=es
```

```json
{"translatedText":"Hola"}
```

--------------------------------

### Run LibreTranslate with WSGI and Gunicorn

Source: https://docs.libretranslate.com/guides/installation

Guides on installing Gunicorn and running LibreTranslate using a WSGI server. Demonstrates how to bind to a specific address and port, and pass application arguments.

```bash
pip install gunicorn
gunicorn --bind 0.0.0.0:5000 'wsgi:app'
```

```bash
gunicorn --bind 0.0.0.0:5000 'wsgi:app(api_keys=True)'
```

--------------------------------

### Install LibreTranslate with Python

Source: https://docs.libretranslate.com/guides/installation

Installs the LibreTranslate Python package and provides a command to run the service. Supports specific Python versions and allows loading only certain languages to reduce startup time.

```bash
pip install libretranslate
libretranslate [args]
```

```bash
libretranslate --load-only en,es,fr
```

--------------------------------

### Install LibreTranslate with Helm Chart

Source: https://docs.libretranslate.com/guides/installation

Provides commands to add the LibreTranslate Helm repository, update it, search for the chart, and install LibreTranslate on Kubernetes.

```bash
helm repo add libretranslate https://libretranslate.github.io/helm-chart/
helm repo update
helm search repo libretranslate
helm install libretranslate libretranslate/libretranslate --namespace libretranslate --create-namespace
```

--------------------------------

### Start a Shell with LibreTranslate Installed

Source: https://docs.libretranslate.com/guides/build_from_sources

Opens a new shell environment with LibreTranslate and its dependencies activated. Allows running the `libretranslate` command or `python main.py` directly.

```shell
hatch shell
libretranslate [args]

# Or
python main.py [args]
```

--------------------------------

### Gunicorn Metrics Setup for Multiprocessing

Source: https://docs.libretranslate.com/guides/installation

Details the steps to configure Gunicorn for multiprocess metrics collection. This involves creating a directory for metric data and exporting the `PROMETHEUS_MULTIPROC_DIR` environment variable before starting the Gunicorn server.

```bash
mkdir -p /tmp/prometheus_data
rm /tmp/prometheus_data/*
export PROMETHEUS_MULTIPROC_DIR=/tmp/prometheus_data
gunicorn -c scripts/gunicorn_conf.py --bind 0.0.0.0:5000 'wsgi:app(metrics=True)'
```

--------------------------------

### Managed Hosting Quickstart

Source: https://docs.libretranslate.com/index

Demonstrates how to perform a translation request using the managed LibreTranslate API via curl, including the use of an API key. Includes the expected JSON response.

```bash
curl -X POST https://libretranslate.com/translate -d q="Hello" -d source=en -d target=es -d api_key=xxxxx
```

```json
{"translatedText":"Hola"}
```

--------------------------------

### Run LibreTranslate with Docker

Source: https://docs.libretranslate.com/guides/installation

Instructions for cloning the LibreTranslate repository and running the application using Docker. Includes a specific command for enabling CUDA GPU acceleration.

```bash
git clone https://github.com/LibreTranslate/LibreTranslate
cd LibreTranslate
./run.sh [args]
```

```bash
docker compose -f docker-compose.cuda.yml up -d --build
```

--------------------------------

### LibreTranslate API Reference

Source: https://docs.libretranslate.com/guides/installation

This section details the available API endpoints for LibreTranslate, covering language detection, translation, file translation, and frontend settings.

```APIDOC
API Endpoints:

1. Detect Language:
   - Endpoint: /detect
   - Method: POST
   - Description: Detects the language of a given text.
   - Example Usage:
     POST /detect
     {
       "q": "Hello world"
     }

2. List Supported Languages:
   - Endpoint: /languages
   - Method: GET
   - Description: Retrieves a list of all supported languages.
   - Example Usage:
     GET /languages

3. Translate Text:
   - Endpoint: /translate
   - Method: POST
   - Parameters:
     - q: The text to translate (string, required)
     - source: The source language code (string, optional, defaults to auto-detect)
     - target: The target language code (string, required)
     - format: The output format (string, optional, defaults to 'text')
     - api_key: Your API key (string, optional)
   - Description: Translates text from a source language to a target language.
   - Example Usage:
     POST /translate
     {
       "q": "Hello world",
       "source": "en",
       "target": "es"
     }

4. Translate File:
   - Endpoint: /translate_file
   - Method: POST
   - Parameters:
     - file: The file to translate (multipart/form-data, required)
     - target: The target language code (string, required)
     - source: The source language code (string, optional, defaults to auto-detect)
     - api_key: Your API key (string, optional)
   - Description: Translates the content of a file.
   - Example Usage:
     POST /translate_file
     (multipart/form-data with 'file' and 'target' parameters)

5. Get Frontend Settings:
   - Endpoint: /frontend/settings
   - Method: GET
   - Description: Retrieves frontend configuration settings.
   - Example Usage:
     GET /frontend/settings

6. Suggest Translation:
   - Endpoint: /suggest
   - Method: POST
   - Parameters:
     - q: The text to suggest translations for (string, required)
     - target: The target language code (string, required)
     - source: The source language code (string, optional)
   - Description: Suggests translations for a given text.
   - Example Usage:
     POST /suggest
     {
       "q": "Hello",
       "target": "fr"
     }
```

--------------------------------

### Run LibreTranslate in Development Mode

Source: https://docs.libretranslate.com/guides/build_from_sources

Starts the LibreTranslate application in debug mode using `hatch`. The application will be accessible at http://localhost:5000.

```shell
hatch run dev --debug
```

--------------------------------

### Install Hatch Build Tool

Source: https://docs.libretranslate.com/guides/build_from_sources

Installs the `hatch` package manager, which is used to manage project dependencies and run development scripts for LibreTranslate.

```shell
pipx install hatch
```

--------------------------------

### Alternative Installation (without Hatch)

Source: https://docs.libretranslate.com/guides/build_from_sources

Provides an alternative method to install LibreTranslate using `pip` directly, bypassing the `hatch` build tool.

```python
pip install -e ".[test]"
```

--------------------------------

### Run Docker Container

Source: https://docs.libretranslate.com/guides/build_from_sources

Starts a LibreTranslate Docker container, mapping port 5000 for access. The `[args]` can include arguments like `--update-models`.

```shell
docker run -it -p 5000:5000 libretranslate [args]
```

--------------------------------

### Update LibreTranslate Software and Models

Source: https://docs.libretranslate.com/guides/installation

Instructions for updating the LibreTranslate application and its language models. Users can update via pip for Python installations or pull the latest image for Docker deployments. Language models can be updated at startup using a specific argument or by running a provided script.

```shell
pip install -U libretranslate
```

```docker
docker pull libretranslate/libretranslate
```

```shell
libretranslate --update-models
./run.sh --update-models
```

```python
scripts/install_models.py
```

--------------------------------

### LibreTranslate Command-Line Arguments

Source: https://docs.libretranslate.com/guides/installation

Configuration options for running the LibreTranslate server. These arguments control host, port, request limits, API key handling, language settings, and more. Environment variables with the prefix 'LT_' can also be used and override defaults but have lower priority than command-line arguments.

```APIDOC
--host: Set host to bind the server to. Default: 127.0.0.1
--port: Set port to bind the server to. Default: 5000
--char-limit: Set character limit. Default: No limit
--req-limit: Set maximum number of requests per minute per client. Default: No limit
--req-limit-storage: Storage URI for request limit data. Default: memory://
--req-time-cost: Considers a time cost (in seconds) for request limiting. Default: No cost
--batch-limit: Set maximum number of texts to translate in a batch request. Default: No limit
--ga-id: Enable Google Analytics on the API client page. Default: Disabled
--frontend-language-source: Set frontend default language - source. Default: auto
--frontend-language-target: Set frontend default language - target. Default: locale
--frontend-timeout: Set frontend translation timeout. Default: 500
--api-keys-db-path: Path for the local API keys database. Default: db/api_keys.db
--api-keys-remote: Remote endpoint to query for valid API keys. Default: Use local db
--get-api-key-link: Show a link in the UI for obtaining API keys. Default: No API link displayed
--shared-storage: Shared storage URI for multi-process data sharing. Default: memory://
--secondary: Mark this instance as a secondary instance. Default: Primary
--load-only: Set available languages. Default: All
--threads: Set number of threads. Default: 4
--metrics-auth-token: Protect the /metrics endpoint with an Authorization Bearer token. Default: No auth
--url-prefix: Add prefix to URL. Default: /
--debug: Enable debug environment. Default: Disabled
--ssl: Enable SSL. Default: Disabled
--api-keys: Enable API keys database for per-client rate limits. Default: Disabled
--require-api-key-origin: Require API key unless request origin matches domain. Default: Disabled
--require-api-key-secret: Require API key unless client sends matching secret. Default: Disabled
--require-api-key-fingerprint: Require API key unless client matches fingerprint. Default: Disabled
--under-attack: Enable under attack mode (requests require API key). Default: Disabled
--suggestions: Allow user suggestions. Default: Disabled
--disable-files-translation: Disable files translation. Default: Enabled
--disable-web-ui: Disable web UI. Default: Enabled
--update-models: Update language models at startup. Default: Disabled
--metrics: Enable the /metrics endpoint for Prometheus metrics. Default: Disabled
```

--------------------------------

### Build and Run with Docker Compose

Source: https://docs.libretranslate.com/guides/build_from_sources

Uses Docker Compose to build and start the LibreTranslate service in detached mode.

```shell
docker compose up -d --build
```

--------------------------------

### LibreTranslate HTTP Metrics

Source: https://docs.libretranslate.com/guides/installation

Exposes LibreTranslate's HTTP request metrics in Prometheus exposition format. These metrics track requests in flight and request duration, providing insights into API performance.

```prometheus
# TYPE libretranslate_http_requests_in_flight gauge
libretranslate_http_requests_in_flight{api_key="",endpoint="/translate",request_ip="127.0.0.1"} 0.0

# HELP libretranslate_http_request_duration_seconds Multiprocess metric
# TYPE libretranslate_http_request_duration_seconds summary
libretranslate_http_request_duration_seconds_count{api_key="",endpoint="/translate",request_ip="127.0.0.1",status="200"} 0.0
libretranslate_http_request_duration_seconds_sum{api_key="",endpoint="/translate",request_ip="127.0.0.1",status="200"} 0.0
```

--------------------------------

### Configure Prometheus to Scrape LibreTranslate

Source: https://docs.libretranslate.com/guides/installation

Provides a sample `prometheus.yml` configuration to enable Prometheus to scrape metrics from a LibreTranslate instance. It specifies the job name and target address.

```yaml
scrape_configs:

- job_name: "libretranslate"

# Needed only if you use --metrics-auth-token
#authorization:
#credentials: "mytoken"
static_configs:
- targets: ["localhost:5000"]
```

--------------------------------

### Externally Managed Environment Error

Source: https://docs.libretranslate.com/guides/build_from_sources

This error occurs when the operating system manages the Python installation. It advises using system package managers (like apt) for system-wide installations or setting up a virtual environment (venv) for project-specific dependencies to prevent conflicts.

```text
error: externally-managed-environment

× This environment is externally managed

╰─> To install Python packages system-wide, try apt install

python3-xyz, where xyz is the package you are trying to

install.

…
```

--------------------------------

### LibreTranslate Prometheus Metrics Endpoint

Source: https://docs.libretranslate.com/guides/installation

Enables the /metrics endpoint for exporting Prometheus usage metrics. When enabled, this endpoint provides insights into the server's performance and usage patterns. The endpoint is protected by default and requires an Authorization Bearer token if `--metrics-auth-token` is set.

```shell
libretranslate --metrics
```

```APIDOC
Endpoint: http://localhost:5000/metrics

Metrics:
  libretranslate_http_requests_in_flight: Multiprocess metric for in-flight HTTP requests.
```

--------------------------------

### Translate Text (JavaScript)

Source: https://docs.libretranslate.com/guides/api_usage

Performs a simple translation of text from a source language to a target language. The API key is optional for self-hosted instances. This example demonstrates the basic POST request structure.

```javascript
const res = await fetch("https://libretranslate.com/translate", {
  method: "POST",
  body: JSON.stringify({
    q: "Hello!",
    source: "en",
    target: "es",
    api_key: "xxxxxx" // can be optional with self-hosting
  }),
  headers: { "Content-Type": "application/json" },
});
console.log(await res.json());
```

--------------------------------

### Update Web UI Locales Meta

Source: https://docs.libretranslate.com/guides/contributing

Example JSON structure for updating locale meta information in the LibreTranslate Web UI. This involves changing a boolean flag to indicate review status.

```json
{
  "name": "<Language>",
  "reviewed": true
}
```

--------------------------------

### Get Alternative Translations (JavaScript)

Source: https://docs.libretranslate.com/guides/api_usage

Requests multiple alternative translations for a given text. The `alternatives` parameter specifies the number of alternatives to return. This can be useful for providing users with different phrasing options.

```javascript
const res = await fetch("https://libretranslate.com/translate", {
  method: "POST",
  body: JSON.stringify({
    q: "Hello",
    source: "en",
    target: "it",
    format: "text",
    alternatives: 3,
    api_key: "xxxxxx"
  }),
  headers: { "Content-Type": "application/json" },
});
console.log(await res.json());
```

--------------------------------

### Clone LibreTranslate Repository

Source: https://docs.libretranslate.com/guides/build_from_sources

Clones the LibreTranslate project from GitHub and navigates into the project directory. `hatch` will automatically set up dependencies and pre-commit hooks.

```shell
git clone https://github.com/LibreTranslate/LibreTranslate.git
cd LibreTranslate
```

--------------------------------

### Run Test Suite and Linting

Source: https://docs.libretranslate.com/guides/build_from_sources

Executes the project's test suite and linting checks using `hatch`. This ensures code quality and functionality.

```shell
hatch run test
```

--------------------------------

### Run Tests with Print Statements

Source: https://docs.libretranslate.com/guides/build_from_sources

Runs the test suite and displays all `print()` output, which is useful for debugging test failures.

```shell
hatch run test -s
```

--------------------------------

### LibreTranslate API Reference - Miscellaneous Endpoints

Source: https://docs.libretranslate.com/guides/contributing

Documentation for miscellaneous LibreTranslate API endpoints, including fetching frontend settings and submitting suggestions.

```APIDOC
API Reference - Miscellaneous Operations:

/frontend/settings GET
  - Description: Retrieves frontend settings, useful for client applications.
  - Returns: An object containing various frontend configuration settings (object).

/suggest POST
  - Description: Allows users to suggest translations or corrections for specific phrases.
  - Parameters:
    - text: The original text (string).
    - translation: The suggested translation (string).
    - language: The language code for the suggestion (string).
    - api_key: Your API key for authentication (string, optional).
  - Returns: A confirmation message indicating the suggestion was received (string).
```

--------------------------------

### LibreTranslate API Reference

Source: https://docs.libretranslate.com/index

Provides an overview of the LibreTranslate API endpoints for translation, language detection, and other utility functions. Includes HTTP methods, paths, and brief descriptions.

```APIDOC
API Endpoints:

- /detect POST
  - Detects the language of a given text.
  - Input: JSON object with 'q' (text to detect).
  - Output: JSON object with detected language and confidence.

- /languages GET
  - Retrieves a list of supported languages.
  - Output: JSON object containing an array of language objects, each with 'code' and 'name'.

- /translate POST
  - Translates text from a source language to a target language.
  - Input: JSON object with 'q' (text), 'source' (source language code), 'target' (target language code), and optional 'api_key'.
  - Output: JSON object with 'translatedText', 'detectedSourceLanguage', and 'alternativeTranslations'.

- /translate_file POST
  - Translates a file from a source language to a target language.
  - Input: Multipart form data with 'file' (the file to translate), 'source' (source language code), 'target' (target language code), and optional 'api_key'.
  - Output: The translated file.

- /frontend/settings GET
  - Retrieves frontend settings, including available languages and models.
  - Output: JSON object with frontend configuration details.

- /suggest POST
  - Suggests translations for a given text and target language.
  - Input: JSON object with 'q' (text), 'target' (target language code), and optional 'source' (source language code).
  - Output: JSON object with suggested translations.
```

--------------------------------

### Prune Hatch Virtual Environment

Source: https://docs.libretranslate.com/guides/build_from_sources

Cleans up and removes unused virtual environments managed by `hatch`.

```shell
hatch env prune
```

--------------------------------

### LibreTranslate API Reference

Source: https://docs.libretranslate.com/community/projects

Overview of the LibreTranslate API endpoints for translation and miscellaneous functionalities. Detailed parameter and return value information is not available in the provided text.

```APIDOC
LibreTranslate API Endpoints:

Translate Operations:
  - /detect POST
    Description: Detects the language of the input text.
    - /languages GET
    Description: Retrieves a list of supported languages.
    - /translate POST
    Description: Translates text from one language to another.
    - /translate_file POST
    Description: Translates an uploaded file.

Miscellaneous Operations:
  - /frontend/settings GET
    Description: Retrieves frontend settings.
  - /suggest POST
    Description: Suggests translations or corrections.
```

--------------------------------

### Build Docker Image

Source: https://docs.libretranslate.com/guides/build_from_sources

Builds the LibreTranslate Docker image. Use `--build-arg with_models=true` to include language models during the build for offline use.

```dockerfile
docker build -f docker/Dockerfile [--build-arg with_models=true] -t libretranslate .
```

--------------------------------

### LibreTranslate API: Miscellaneous Operations

Source: https://docs.libretranslate.com/api/operations/languages

Provides documentation for miscellaneous API endpoints, including fetching frontend settings and suggesting translations.

```APIDOC
GET /frontend/settings
  Description: Retrieves frontend settings, including available languages and default settings.
  Parameters:
    None
  Returns:
    object: Frontend settings.
      languages: Array<object> - List of supported languages.
      default_lang: Default language code (string).
```

```APIDOC
POST /suggest
  Description: Suggests a translation for a given text and target language.
  Parameters:
    text: The text to suggest a translation for (string)
    lang: The target language code (string)
  Returns:
    object:
      suggestion: The suggested translation (string).
```

--------------------------------

### Run Tests on Multiple Python Versions

Source: https://docs.libretranslate.com/guides/build_from_sources

Executes the test suite across all configured Python versions managed by `hatch`.

```shell
hatch run all:test
```

--------------------------------

### LibreTranslate API Endpoints

Source: https://docs.libretranslate.com/api

This section details the available API endpoints for LibreTranslate. It includes the HTTP method, path, and a brief description of the functionality provided by each endpoint.

```APIDOC
API Reference:

translate:
  - /detect POST
    - Detects the language of a given text.
  - /languages GET
    - Retrieves a list of supported languages.
  - /translate POST
    - Translates text from a source language to a target language.
  - /translate_file POST
    - Translates the content of a file from a source language to a target language.

misc:
  - /frontend/settings GET
    - Retrieves frontend settings, potentially including available languages or configurations.
  - /suggest POST
    - Allows users to suggest translations or corrections.
```

--------------------------------

### Retrieve Frontend Settings API

Source: https://docs.libretranslate.com/api/operations/frontendsettings

Fetches the current frontend settings of the LibreTranslate API. This includes information about API key requirements, character limits, timeouts, and supported file formats.

```APIDOC
GET /frontend/settings

Description:
  Retrieves frontend settings for the LibreTranslate service.

Parameters:
  None

Responses:
  200 OK:
    Description: Frontend settings object.
    Content:
      application/json:
        Schema:
          type: object
          properties:
            apiKeys:
              type: boolean
              description: Indicates if the API key database is enabled.
            charLimit:
              type: integer
              description: Character input limit for a language (-1 indicates no limit).
            frontendTimeout:
              type: integer
              description: Frontend translation timeout in milliseconds.
            keyRequired:
              type: boolean
              description: Indicates if an API key is required for requests.
            language:
              type: object
              description: Details about the language configuration.
              properties:
                source:
                  type: object
                  description: Source language details.
                  properties:
                    code:
                      type: string
                      description: The language code (e.g., 'en').
                    name:
                      type: string
                      description: The human-readable name of the language (in English).
                target:
                  type: object
                  description: Target language details.
                  properties:
                    code:
                      type: string
                      description: The language code (e.g., 'fr').
                    name:
                      type: string
                      description: The human-readable name of the language (in English).
            suggestions:
              type: boolean
              description: Indicates if submitting suggestions is enabled.
            supportedFilesFormat:
              type: array
              items:
                type: string
              description: An array of supported file formats for translation.
```

--------------------------------

### LibreTranslate API Reference - Translation Endpoints

Source: https://docs.libretranslate.com/guides/contributing

Documentation for core LibreTranslate API endpoints related to translation and language detection. Includes methods for detecting language, listing supported languages, translating text, and translating files.

```APIDOC
API Reference - Translation Operations:

/detect POST
  - Description: Detects the language of a given text.
  - Parameters:
    - q: The text to detect the language of (string).
  - Returns: An object containing the detected language code (string).
  - Example:
    POST /detect
    {
      "q": "Hello world"
    }

/languages GET
  - Description: Retrieves a list of all supported languages.
  - Returns: An array of language objects, each with 'code' and 'name' properties (array of objects).

/translate POST
  - Description: Translates text from a source language to a target language.
  - Parameters:
    - q: The text to translate (string).
    - source: The source language code (string, optional, auto-detects if not provided).
    - target: The target language code (string, required).
    - format: The format of the input text ('text' or 'html', defaults to 'text').
    - api_key: Your API key for authentication (string, optional).
  - Returns: An object containing the translated text, source language, and target language (object).
  - Example:
    POST /translate
    {
      "q": "Hello world",
      "source": "en",
      "target": "es"
    }

/translate_file POST
  - Description: Translates an uploaded file from a source language to a target language.
  - Parameters:
    - file: The file to translate (multipart/form-data).
    - source: The source language code (string, optional).
    - target: The target language code (string, required).
    - api_key: Your API key for authentication (string, optional).
  - Returns: The translated file content.
```

--------------------------------

### LibreTranslate API Key Management Commands

Source: https://docs.libretranslate.com/guides/manage_api_keys

Commands for managing API keys in self-hosted LibreTranslate instances. These commands allow you to add new keys with specific rate and character limits, remove existing keys, and view all managed keys. The `--api-keys-db-path` option can be used to specify a custom database path.

```APIDOC
ltmanage keys add <requests_per_minute> [--char-limit <characters_per_request>] [--api-keys-db-path <path>]
  - Adds a new API key with specified request limits per minute and an optional character limit per request.
  - Example: ltmanage keys add 120
  - Example with char limit: ltmanage keys add 120 --char-limit 5000
  - Example with custom DB path: ltmanage keys --api-keys-db-path path/to/db/dbName.db add 120
```

```APIDOC
ltmanage keys remove <api-key> [--api-keys-db-path <path>]
  - Removes an existing API key from the LibreTranslate instance.
  - Example: ltmanage keys remove YOUR_API_KEY_HERE
  - Example with custom DB path: ltmanage keys --api-keys-db-path path/to/db/dbName.db remove YOUR_API_KEY_HERE
```

```APIDOC
ltmanage keys [--api-keys-db-path <path>]
  - Lists all currently managed API keys and their associated limits.
  - Example: ltmanage keys
  - Example with custom DB path: ltmanage keys --api-keys-db-path path/to/db/dbName.db
```

--------------------------------

### LibreTranslate API: Translation & Detection

Source: https://docs.libretranslate.com/api/operations/languages

Provides documentation for core translation and language detection API endpoints. Includes methods for detecting language, translating text, translating files, and listing supported languages.

```APIDOC
GET /languages
  Description: Retrieves a list of all supported languages for translation.
  Parameters:
    None
  Returns:
    Array<object>: A list of supported languages.
      object:
        code: Language code (string)
        name: Human-readable language name (string)
        targets: Supported target language codes (Array<string>)
  Example:
    GET /languages
    Response:
      [
        {
          "code": "en",
          "name": "English",
          "targets": ["es", "fr", "de"]
        }
      ]
```

```APIDOC
POST /detect
  Description: Detects the language of a given text.
  Parameters:
    q: The text to detect the language of (string)
  Returns:
    object:
      language: The detected language code (string)
      confidence: The confidence score of the detection (float)
  Example:
    POST /detect
    Body:
      {
        "q": "Hello world"
      }
    Response:
      {
        "language": "en",
        "confidence": 0.99
      }
```

```APIDOC
POST /translate
  Description: Translates text from a source language to a target language.
  Parameters:
    q: The text to translate (string)
    source: The source language code (string, optional, auto-detected if omitted)
    target: The target language code (string, required)
    format: The format of the text (string, optional, defaults to 'text')
  Returns:
    object:
      translatedText: The translated text (string)
      detectedSourceLanguage: The detected source language code (string, if source was omitted)
  Example:
    POST /translate
    Body:
      {
        "q": "Hello world",
        "target": "es"
      }
    Response:
      {
        "translatedText": "Hola mundo",
        "detectedSourceLanguage": "en"
      }
```

```APIDOC
POST /translate_file
  Description: Translates a file from a source language to a target language.
  Parameters:
    file: The file to translate (multipart/form-data)
    source: The source language code (string, optional, auto-detected if omitted)
    target: The target language code (string, required)
  Returns:
    The translated file content.
```

--------------------------------

### LibreTranslate API Endpoints

Source: https://docs.libretranslate.com/api/operations/translate

This section details the available API endpoints for LibreTranslate, including their methods, parameters, and expected responses. It covers core translation functionality, language detection, file translation, and utility endpoints.

```APIDOC
LibreTranslate API Reference:

Overview:
  Provides RESTful endpoints for machine translation services.

Endpoints:

1.  /translate POST
    Translates text from a source language to a target language.
    Parameters:
      - q (string or array<string>): Required. Text(s) to translate.
      - source (string): Required. Source language code (e.g., 'en') or 'auto' for auto-detection.
      - target (string): Required. Target language code (e.g., 'es').
      - format (string, optional): Format of source text. Allowed values: 'text', 'html'. Defaults to 'text'.
      - alternatives (integer, optional): Preferred number of alternative translations. Defaults to 0.
      - api_key (string, optional): Your API key for authentication.
    Responses:
      - 200 OK: Translation successful.
        - translatedText (string or array<string>): The translated text.
        - alternatives (array<string> or array<array<string>>): Alternative translations.
        - detectedLanguage (object or array<object>): Information about the detected source language (if 'auto' was used).
          - language (string): Detected language code.
          - confidence (number): Confidence score (0-100).
      - 400 Bad Request: Invalid request parameters.
      - 403 Forbidden: API key is banned or invalid.
      - 429 Too Many Requests: Rate limit exceeded.
      - 500 Internal Server Error: Translation service error.
    Example:
      POST /translate
      Content-Type: application/x-www-form-urlencoded
      q=Hello world!
      source=en
      target=es

2.  /detect POST
    Detects the language of a given text.
    Parameters:
      - q (string or array<string>): Required. Text(s) for language detection.
    Responses:
      - 200 OK: Language detection successful.
        - language (string): Detected language code.
        - confidence (number): Confidence score (0-100).
      - 400 Bad Request: Invalid request parameters.
      - 500 Internal Server Error: Detection service error.

3.  /languages GET
    Retrieves a list of supported languages.
    Responses:
      - 200 OK: List of languages.
        - languages (array<object>): Array of language objects.
          - code (string): Language code (e.g., 'en').
          - name (string): Language name (e.g., 'English').

4.  /translate_file POST
    Translates the content of a file.
    Parameters:
      - file (file): Required. The file to translate.
      - target (string): Required. Target language code.
      - source (string, optional): Source language code or 'auto'.
      - format (string, optional): Format of source file content ('text' or 'html'). Defaults to 'text'.
      - api_key (string, optional): Your API key.
    Responses:
      - 200 OK: File translation successful.
        - translatedText (string): The translated file content.
      - 400 Bad Request: Invalid request parameters or file format.
      - 403 Forbidden: API key is banned or invalid.
      - 429 Too Many Requests: Rate limit exceeded.
      - 500 Internal Server Error: Translation service error.

5.  /frontend/settings GET
    Retrieves frontend settings, potentially including available languages and default configurations.
    Responses:
      - 200 OK: Frontend settings.

6.  /suggest POST
    Allows users to suggest translations for specific phrases.
    Parameters:
      - text (string): Required. The text to suggest a translation for.
      - original_language (string): Required. The original language of the text.
      - translated_language (string): Required. The target language for the translation.
      - suggestion (string): Required. The suggested translation.
    Responses:
      - 200 OK: Suggestion received.
      - 400 Bad Request: Missing required parameters.
      - 500 Internal Server Error: Suggestion service error.

Authentication:
  API keys can be used via the 'api_key' parameter for authenticated requests.
```

--------------------------------

### Discourse Plugin Configuration

Source: https://docs.libretranslate.com/guides/integrations

Configuration snippet for the Discourse translator plugin to integrate LibreTranslate. This involves modifying the \"app.yml\" file and rebuilding the Discourse application.

```yaml
## Plugins go here

## see https://meta.discourse.org/t/19157 for details

hooks:

after_code:
- exec:
    cd: $home/plugins
    cmd:
    - git clone https://github.com/discourse/docker_manager.git

    - git clone https://github.com/discourse/discourse-translator

...
```