Weblate

Common errors

• ModuleNotFoundError: No module named 'weblate'

  cause The `weblate` package is not installed in the current Python environment or the virtual environment is not activated.
  fix Ensure you have installed Weblate: `pip install 'weblate[all]'` (recommended) or `pip install weblate`. If using a virtual environment, activate it first.

• django.db.utils.OperationalError: no such table: main.django_migrations

  cause The Django database migrations have not been applied, or the database connection is misconfigured.
  fix Ensure your database settings are correct in `settings.py` and run Weblate's migration command: `weblate migrate`. For fresh installations, ensure the database is initialized.

• django.core.exceptions.ImproperlyConfigured: The SECRET_KEY setting must not be empty.

  cause The `SECRET_KEY` is a mandatory Django setting, crucial for security, and is missing from your Weblate configuration.
  fix Set a strong `SECRET_KEY` in your Weblate's `settings.py` or via the `WEBLATE_SECRET_KEY` environment variable. Generate a new, unique key for production environments.

• AttributeError: 'WeblateAPI' object has no attribute 'some_new_method' (or similar API client method missing)

  cause You are using an older version of the `weblate_api` client library that does not support features introduced in a newer Weblate server version.
  fix Upgrade the `weblate_api` client library to match or exceed the version of your Weblate server: `pip install --upgrade weblate_api`.

Warnings

• breaking Weblate has strict Python version requirements. Version 5.17 (and generally 5.2+) requires Python 3.12 or newer. Older versions required Python 3.10/3.11. Ensure your environment matches.
  Fix: Upgrade your Python environment to 3.12+ before installing or upgrading Weblate 5.2+. Check Weblate's release notes for specific version compatibility.
• breaking Weblate's major versions are often tied to specific Django versions. Upgrading Weblate without ensuring Django compatibility can lead to `django.core.exceptions.ImproperlyConfigured` or migration failures.
  Fix: Always consult Weblate's official documentation and release notes for the required Django version for your specific Weblate release. For Weblate 5.17, Django >=4.2,<5.2 is required.
• gotcha There are two distinct Python packages: `weblate` (the server application) and `weblate_api` (a client library for Weblate's API). Do not confuse them; `weblate` provides the server, while `weblate_api` is used by *other* Python applications to interact with a running Weblate instance.
  Fix: Use `pip install weblate` to set up the Weblate server. Use `pip install weblate_api` in *separate* projects if you want to programmatically interact with a Weblate API. Do not try to import API client functionality directly from the `weblate` package.
• gotcha Database migrations are critical for Weblate upgrades. Skipping them or running them incorrectly can corrupt your translation data.
  Fix: Always run `weblate migrate` (or `django-admin migrate` in a Weblate context) after upgrading Weblate, and always back up your database before performing major upgrades.

Install

• pip install 'weblate[all]' # For a full installation with all dependencies Full installation
• pip install weblate # For a minimal installation, dependencies will need to be added separately Minimal installation

Imports

• BaseCheck

  from weblate.checks.base import BaseCheck

  Common import for defining custom translation checks within Weblate.
• BaseAddon

  from weblate.addons.base import BaseAddon

  Common import for defining custom add-ons to extend Weblate's functionality.
• messages
  wrong:

  from weblate.trans.messages import Message

  correct:

  from weblate.trans.models import TranslationEntry as messages

  The core translation entry model was moved/renamed. Direct access is often via 'TranslationEntry'.

Quickstart

This quickstart demonstrates how to define a custom translation check for Weblate. Weblate is a Django application, and its 'library' usage primarily involves extending its functionality (e.g., custom checks, add-ons) by importing its base classes. This code is not standalone runnable but serves as an example of an extension you would integrate into a running Weblate instance by configuring it in `settings.py`.

import os
from weblate.checks.base import BaseCheck
from weblate.checks.base import CheckResult, WARNING

# This example defines a custom Weblate check.
# To run it, you would add it to your Weblate configuration (settings.py).
# It is not directly executable as a standalone script outside a Weblate instance.

class MyCustomLengthCheck(BaseCheck):
    # Unique ID for the check
    check_id = 'my-custom-length-check'
    # Human-readable name
    name = 'Too Long Translation Check'
    # Description for the user interface
    description = 'Checks if a translation exceeds a maximum allowed length.'
    # Default parameters, configurable via Weblate UI
    params = {'max_length': 50}

    def check(self, check_context):
        translation = check_context.translation
        source = check_context.source_string

        if translation and translation.text and source and source.text:
            max_len = self.get_param('max_length')
            if len(translation.text) > max_len:
                yield CheckResult(
                    start=0,
                    end=len(translation.text),
                    severity=WARNING,
                    message=f'Translation is too long ({len(translation.text)} chars), max allowed is {max_len} chars.'
                )

# Example of how you *might* register it (typically done in settings.py):
# WLB_CHECKS = {'my-custom-length-check': 'my_module.my_custom_check.MyCustomLengthCheck'}

print("Custom check 'MyCustomLengthCheck' defined. Register it in your Weblate settings.py to use it.")