Customizing Weblate¶

Extend and customize using Django and Python. Contribute your changes upstream so that everybody can benefit. This reduces your maintenance costs; code in Weblate is taken care of when changing internal interfaces or refactoring the code.

Hint

You can also customize Weblate look in Appearance customization.

Warning

Neither internal interfaces nor templates are considered a stable API. Please review your customizations for every upgrade, the interfaces or their semantics might change without notice.

Creating a Python module¶

If you are not familiar with Python, you might want to look into Python For Beginners, explaining the basics and pointing to further tutorials.

To write a file with custom Python code (called a module), a place to store it is needed, either in the system path (usually something like /usr/lib/python3.12/site-packages/) or in the Weblate directory, which is also added to the interpreter search path.

Hint

When using Docker, you can place Python modules in /app/data/python/ (see Docker container volumes), so they can be loaded by Weblate, for example from a settings override file.

Better yet, turn your customization into a proper Python package:

Create a folder for your package (we will use weblate_customization).

Within it, create a pyproject.toml file to describe the package:

[build-system]
requires = ["uv_build>=0.8.18,<0.9.0"]
build-backend = "uv_build"

[project]
name = "weblate-customization"
version = "0.1.0"
description = "Add your description here"
requires-python = ">=3.13"
dependencies = []

Create a folder for the Python module: src/weblate_customization
Within it, create a __init__.py file to ensure Python can import the module.
This package can now be installed using uv pip install -e. More info to be found in Editable packages documentation.
Once installed, the module can be used in the Weblate configuration (for example weblate_customization.checks.FooCheck).

Your package structure should look like this:

weblate_customization
├── pyproject.toml
└── src
    └── weblate_customization
        ├── __init__.py
        ├── addons.py
        └── checks.py

You can find an example of customizing Weblate at <https://github.com/WeblateOrg/customize-example>, it covers all the topics described below.

Changing the logo¶

Create a simple Django app containing the static files you want to overwrite (see Creating a Python module).

Branding appears in the following files:

icons/weblate.svg
Logo shown in the navigation bar.

logo-*.png
Web icons depending on screen resolution and web-browser.

favicon.ico
Web icon used by legacy browsers.

weblate-*.png
Avatars for bots or anonymous users. Some web-browsers use these as shortcut icons.

email-logo.png
Used in notifications e-mails.

Add it to INSTALLED_APPS:

INSTALLED_APPS = (
    # Add your customization as first
    "weblate_customization",
    # Weblate apps are here…
)

Run weblate collectstatic --noinput, to collect static files served to clients.

Custom quality checks, add-ons, automatic suggestions and auto-fixes¶

To install your code for Custom automatic fixups, Writing own checks, Custom machine translation or Writing add-on in Weblate:

Place the files into your Python module containing the Weblate customization (see Creating a Python module or Customizing code).
Add its fully-qualified path to the Python class in the dedicated settings:

# Checks
CHECK_LIST += ("weblate_customization.checks.FooCheck",)

# Autofixes
AUTOFIX_LIST += ("weblate_customization.autofix.FooFixer",)

# Add-ons
WEBLATE_ADDONS += ("weblate_customization.addons.ExamplePreAddon",)

# Automatic suggestions
WEBLATE_MACHINERY += ("weblate_customization.machinery.SampleTranslation",)