Weblate

https://docs.weblate.org/en/latest/
Admin
Weblate is a libre software web-based continuous localization system designed to simplify the...
Tokens:485,073
Snippets:4,095
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### Start the development server

Source: https://docs.weblate.org/en/latest/contributing/start.html

Starts the Weblate development server using uv.

```bash
uv run weblate runserver

```

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

### Install Weblate with specific optional features

Source: https://docs.weblate.org/en/latest/admin/install.html

Use this pip command to install Weblate with a custom set of optional features, specified as a comma-separated list in brackets. The example installs the Postgres, Amazon, and SAML features.

```bash
uv pip install "weblate[Postgres,Amazon,SAML]"

```

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

### Install production server components with zypper

Source: https://docs.weblate.org/en/latest/admin/install/venv-suse.html

Installs optional components for running a production server, including web server options, caching, database, SMTP, and gettext tools. Choose the web server option that fits your setup.

```bash
# Web server option 1: NGINX and uWSGI
zypper install nginx uwsgi uwsgi-plugin-python3

# Web server option 2: Apache with ``mod_wsgi``
zypper install apache2 apache2-mod_wsgi

# Caching backend: Valkey
zypper install valkey-server

# Database server: PostgreSQL
zypper install postgresql postgresql-contrib

# SMTP server
zypper install postfix

# Gettext tools for gettext POT/PO update add-ons
zypper install gettext

```

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

### DEFAULT_ADDONS configuration example

Source: https://docs.weblate.org/en/latest/admin/config.html

Example of setting DEFAULT_ADDONS to install add-ons for every newly created component. The dictionary maps add-on names to their parameters; an empty dictionary means no parameters. This setting only affects newly created components.

```python
DEFAULT_ADDONS = {
    # Add-on with no parameters
    "weblate.flags.target_edit": {},
    # Add-on with parameters
    "weblate.autotranslate.autotranslate": {
        "mode": "suggest",
        "filter_type": "todo",
        "auto_source": "mt",
        "component": "",
        "engines": ["weblate-translation-memory"],
        "threshold": "80",
    },
}

```

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

### Install Weblate and development dependencies

Source: https://docs.weblate.org/en/latest/contributing/start.html

Installs Weblate and all dependencies useful for development using uv.

```bash
uv sync --all-extras --dev

```

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

### Install wlc with pip

Source: https://docs.weblate.org/en/latest/python.html

Install the Weblate Client package using pip.

```bash
pip install wlc

```

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

### Run weblate command after pip or setup.py installation

Source: https://docs.weblate.org/en/latest/admin/management.html

After installing Weblate via pip or setup.py, the weblate command is available on the path (or Python environment path). The example runs list_versions.

```bash
weblate list_versions

```

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

### Start remaining services and follow logs

Source: https://docs.weblate.org/en/latest/admin/backup.html

Starts all services and follows the logs. The Weblate container performs database migrations on startup.

```bash
docker compose up -d
docker compose logs -f

```

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

### GET /api/projects/(project)/repository/ - Example JSON data

Source: https://docs.weblate.org/en/latest/api.html

Example response for the repository status endpoint. Shows included and skipped components, permission blockers, and flags for pending commit, merge, and push.

```json
{
    "included_components": ["hello/app"],
    "needs_commit": true,
    "needs_merge": false,
    "needs_push": true,
    "permission_blockers": ["shared/glossary"],
    "skipped_components": ["hello/glossary"]
}
```

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

### Configure .weblate and show project details

Source: https://docs.weblate.org/en/latest/wlc.html

Shows how to configure the project in .weblate and then display its details with wlc show.

```shell
$ cat .weblate
[weblate]
url = https://hosted.weblate.org/api/
translation = weblate/application

$ wlc show
branch: main
file_format: po
source_language: en
filemask: weblate/locale/*/LC_MESSAGES/django.po
git_export: https://hosted.weblate.org/git/weblate/application/
license: GPL-3.0+
license_url: https://spdx.org/licenses/GPL-3.0+
name: Application
new_base: weblate/locale/django.pot
project: weblate
repo: git://github.com/WeblateOrg/weblate.git
slug: application
template:
url: https://hosted.weblate.org/api/components/weblate/application/
vcs: git
web_url: https://hosted.weblate.org/projects/weblate/application/

```

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

### Example request to /api/

Source: https://docs.weblate.org/en/latest/api.html

Shows a GET request to the API root with an Authorization header using a token.

```http
GET /api/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript
Authorization: Token YOUR-TOKEN

```

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

### weblate backup command examples

Source: https://docs.weblate.org/en/latest/admin/management.html

Examples of using the backup command: listing backup services, running a specific service with verbosity 2, and running all enabled services.

```bash
weblate backup --list
```

```bash
weblate backup --service 1 --verbosity 2
```

```bash
weblate backup --all
```

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

### Example Stringsdict file

Source: https://docs.weblate.org/en/latest/formats/stringsdict.html

A minimal example of a .stringsdict file with a single key 'hello' and its localized string.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
    <dict>
        <key>hello</key>
        <dict>
            <key>NSStringLocalizedFormatKey</key>
            <string>Hello, world!
</string>
        </dict>
    </dict>
</plist>

```

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

### wlc configuration file example

Source: https://docs.weblate.org/en/latest/wlc.html

Example configuration file for wlc, placed in ~/.config/weblate. Sets the API URL and scopes the API key to that URL. This is the recommended configuration format.

```ini
[weblate]
url = https://hosted.weblate.org/api/

[keys]
https://hosted.weblate.org/api/ = APIKEY

```

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

### weblate analyze_translator_work command example

Source: https://docs.weblate.org/en/latest/admin/management.html

Analyzes change history to estimate translator throughput per day, with options to limit by project, component, language, and date range. The example limits analysis to the 'weblate' project starting from 2026-01-01.

```bash
weblate analyze_translator_work --project weblate --since 2026-01-01
```

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

### Example add-on implementation

Source: https://docs.weblate.org/en/latest/contributing/addons.html

A complete example of a Weblate add-on class, showing the required attributes (compat, events, name, verbose, description) and a pre_commit callback. It filters for PO file formats and listens to the pre-commit event.

```python
# Copyright © Michal Čihař <michal@weblate.org>
#
# SPDX-License-Identifier: GPL-3.0-or-later

from __future__ import annotations

from typing import TYPE_CHECKING, ClassVar

from django.utils.translation import gettext_lazy

from weblate.addons.base import BaseAddon
from weblate.addons.events import AddonEvent

if TYPE_CHECKING:
    from weblate.addons.base import CompatDict
    from weblate.trans.models import Translation


class ExampleAddon(BaseAddon):
    # Filter for compatible components, every key is
    # matched against property of component
    compat: ClassVar[CompatDict] = {
        "file_format": {"po", "po-mono"},
    }
    # List of events add-on should receive
    events: ClassVar[set[AddonEvent]] = {
        AddonEvent.EVENT_PRE_COMMIT,
    }
    # Add-on unique identifier
    name = "weblate.example.example"
    # Verbose name shown in the user interface
    verbose = gettext_lazy("Example add-on")
    # Detailed add-on description
    description = gettext_lazy("This add-on does nothing it is just an example.")

    # Callback to implement custom behavior
    def pre_commit(
        self,
        translation: Translation | None,
        author: str,
        store_hash: bool,
        activity_log_id: int | None = None,
    ) -> None:
        return

```

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

### Example JSON data for a role

Source: https://docs.weblate.org/en/latest/api.html

Shows the JSON structure returned by GET /api/roles/(int:id)/. Includes name, permissions array, and URL.

```json
{
    "name": "Access repository",
    "permissions": [
        "vcs.access",
        "vcs.view"
    ],
    "url": "http://example.com/api/roles/1/",
}
```

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

### Install production server components

Source: https://docs.weblate.org/en/latest/admin/install/venv-debian.html

Installs optional software for running a production server, including web server options, caching, database, SMTP, and gettext tools. Run as root or with sudo.

```bash
# Web server option 1: NGINX and uWSGI
apt install -y nginx uwsgi uwsgi-plugin-python3

# Web server option 2: Apache with ``mod_wsgi``
apt install -y apache2 libapache2-mod-wsgi-py3

# Caching backend: Valkey
apt install -y valkey-server

# Database server: PostgreSQL
apt install -y postgresql postgresql-contrib

# SMTP server
apt install -y exim4

# Gettext tools for gettext POT/PO update add-ons
apt install -y gettext

```

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

### POTFILES manifest for mixed source formats

Source: https://docs.weblate.org/en/latest/admin/addons.html

Example of a POTFILES manifest listing repository-relative source paths for mixed-format extraction. Blank lines and lines starting with # are ignored.

```text
common/messages.py
qt/application.desktop
qt/application.policy
data/application.metainfo.xml
```

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

### Run database migration

Source: https://docs.weblate.org/en/latest/admin/install/venv-macos.html

Creates the database and its structure for Weblate. The example settings use PostgreSQL.

```bash
weblate migrate

```

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

### MDX example file with front matter and JSX

Source: https://docs.weblate.org/en/latest/formats/mdx.html

Example MDX file showing front matter, imports, exports, JSX components, and Markdown text. Weblate extracts translatable Markdown text while preserving imports, exports, JSX components, and expressions. MDX units automatically get the md-text, auto-safe-html, strict-same, and safe-mdx flags.

```markdown
---
title: Ahoj světe!
description: Learn with Weblate
---

import LessonCard from "./LessonCard"
export const metadata = { slug: "intro" }

# Ahoj světe!

<LessonCard title="Keep this code" count={5}>
  Do not translate this JSX body.
</LessonCard>

Orangutan has five bananas.

Try Weblate at [weblate.org](https://demo.weblate.org/)!

*Thank you for using Weblate.*

```

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

### Start development server

Source: https://docs.weblate.org/en/latest/admin/install/venv-macos.html

Starts the Weblate development server. For production, see the Running server documentation.

```bash
weblate runserver

```

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

### Example JSON data for GET /api/groups/(int:id)/

Source: https://docs.weblate.org/en/latest/api.html

Shows the JSON structure returned by the group detail endpoint. Includes fields like name, defining_project, project_selection, language_selection, and links to related resources.

```json
{
    "name": "Guests",
    "defining_project": null,
    "project_selection": 3,
    "language_selection": 1,
    "url": "http://example.com/api/groups/1/",
    "roles": [
        "http://example.com/api/roles/1/",
        "http://example.com/api/roles/2/"
    ],
    "languages": [
        "http://example.com/api/languages/en/",
        "http://example.com/api/languages/cs/",
    ],
    "projects": [
        "http://example.com/api/projects/demo1/",
        "http://example.com/api/projects/demo/"
    ],
    "componentlist": "http://example.com/api/component-lists/new/",
    "components": [
        "http://example.com/api/components/demo/weblate/"
    ],
    "admins": [
        "http://example.com/api/users/exampleusername/"
    ]
}
```

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

### Start the development application with ./rundev.sh

Source: https://docs.weblate.org/en/latest/contributing/start.html

Starts the Weblate development environment. Equivalent to `./scripts/devcontainer --profile app up`. Builds the development image, starts Weblate with supervised web and Celery workers, and prints the application and Maildev mailbox URLs when ready. Sign in as `admin` with password `admin`.

```bash
./rundev.sh

```

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

### GET /api/components/{project}/{component}/addons/kotlin-sdk/builds/{package}/{version}/

Source: https://docs.weblate.org/en/latest/api.html

Retrieves registration response fields for an existing Kotlin SDK CDN build. Requires the Kotlin SDK CDN add-on and component.edit permission. Returns 404 if the installation or registration is missing.

```APIDOC
## GET /api/components/{project}/{component}/addons/kotlin-sdk/builds/{package}/{version}/

### Description
Return the registration response fields for an existing build. Requires the Kotlin SDK CDN add-on (`weblate.cdn.kotlin`) installed directly on the component and `component.edit` permission.

### Method
GET

### Endpoint
/api/components/{project}/{component}/addons/kotlin-sdk/builds/{package}/{version}/

### Parameters
#### Path Parameters
- **project** (string) - Required - Project identifier.
- **component** (string) - Required - Component identifier.
- **package** (string) - Required - Package name.
- **version** (integer) - Required - Version code.

### Response
#### Success Response (200)
- **packageName** (string) - Package name.
- **versionCode** (integer) - Version code.
- **status** (string) - Status of the build: `pending`, `published`, `failed`, or `retired`.
- **error** (string) - Error message.
- **status_url** (string) - URL to check status.
- **manifest_url** (string) - URL to the manifest.

#### Error Response (404)
- **error** (string) - Error message.

#### Response Example
{
  "packageName": "com.example.app",
  "versionCode": 1,
  "status": "published",
  "error": null,
  "status_url": "https://example.com/status",
  "manifest_url": "https://example.com/manifest"
}
```

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

### Sequence example: group two translation passes

Source: https://docs.weblate.org/en/latest/admin/automation.html

Groups two automatic translation actions in a sequence. The first reuses other components, the second applies local translation memory. The sequence finishes before the next sibling action starts. Outputs are exposed as results.reused and results.memory.

```yaml
- sequence:
    - action: weblate.automatic_translation
      id: reused
      settings:
        auto_source: others
        mode: translate
        q: "state:<translated"
    - action: weblate.automatic_translation
      id: memory
      settings:
        auto_source: mt
        engines: [weblate-translation-memory]
        threshold: 95
        mode: translate
        q: "state:<translated"

```

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

### Install Weblate with ASGI support for Granian

Source: https://docs.weblate.org/en/latest/admin/install.html

Install Weblate with the asgi optional dependency to run Granian with ASGI.

```bash
uv pip install Weblate[all,asgi]
```

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

### Run tests with ./rundev.sh test

Source: https://docs.weblate.org/en/latest/contributing/start.html

Runs pytest with the given arguments. The example runs only tests in the `weblate.machine` module with `--exitfirst`. Automatically starts and bootstraps the development container using Docker Compose, without requiring the Dev Container CLI. Runs independently of the application and workers.

```bash
./rundev.sh test --exitfirst weblate/machine

```
Tokens:
Raw