Разработка надстроек¶

Дополнения — это способ настройки рабочего процесса локализации в Weblate.

class weblate.addons.base.BaseAddon(storage)¶

Base class for Weblate add-ons.

classmethod can_install(*, component=None, category=None, project=None) → bool¶: Check whether add-on is compatible with given component.

change_event(change, activity_log_id: int | None = None)¶: Event handler for change event.

check_change_action(change) → bool¶: Early filtering of Change actions before triggering change_event callback.

component_update(component, activity_log_id: int | None = None)¶: Event handler for component update.

configure(configuration) → None¶: Save configuration.

daily(component=None, category=None, project=None, activity_log_id: int | None = None)¶

Scope-aware daily entry point.

Override this for project-level logic, or override daily_component() for per-component logic.

daily_component(component, activity_log_id: int | None = None)¶: Per-component daily processing. Override this for component-level logic.

classmethod get_add_form(user, *, component=None, category=None, project=None, **kwargs)¶: Return configuration form for adding new add-on.

classmethod get_api_urls()¶: Return named Django URL patterns for this provider’s API.

get_change_details(compared_configuration)¶: Return a public configuration snapshot and changed field names.

get_public_configuration()¶: Return configuration with non-public values redacted.

classmethod get_public_configuration_fields() → frozenset[str]¶: Return configuration fields which are safe for public use.

get_settings_form(user, **kwargs)¶: Return configuration form for this add-on.

manual(component=None, category=None, project=None, activity_log_id: int | None = None)¶

Scope-aware manual entry point.

By default this mirrors the daily handler and lets add-ons opt in explicitly by subscribing to the manual event.

manual_component(component, activity_log_id: int | None = None)¶: Per-component manual processing.

post_add(translation, activity_log_id: int | None = None)¶: Event handler after new translation is added.

post_commit(component, store_hash: bool, activity_log_id: int | None = None)¶: Event handler after changes are committed to the repository.

post_install(component, store_hash: bool, activity_log_id: int | None = None)¶: Event handler after add-on is installed.

post_push(component, activity_log_id: int | None = None)¶: Event handler after repository is pushed upstream.

post_remove(translation, activity_log_id: int | None = None)¶: Event handler after a translation is removed.

post_update(component, previous_head: str, skip_push: bool, changed_files: list[str], parse_after_update: bool = False, activity_log_id: int | None = None)¶

Event handler after repository is updated from upstream.

Параметры:

previous_head (str) – HEAD of the repository prior to update, can be blank on initial clone.
skip_push (bool) – Whether the add-on operation should skip pushing changes upstream. Usually you can pass this to underlying methods as commit_and_push or commit_pending.
changed_files (list[str]) – Files changed by the repository update.

pre_commit(translation, author: str, store_hash: bool, activity_log_id: int | None = None)¶: Event handler before changes are committed to the repository.

pre_push(component, activity_log_id: int | None = None)¶: Event handler before repository is pushed upstream.

pre_update(component, activity_log_id: int | None = None)¶: Event handler before repository is updated from upstream.

preview(workflow: object, component_id: int | None, change_id: int | None = None, actor=None) → dict[str, object]¶: Preview an operation without changing application state, if supported.

resolve_components(*, component=None, category=None, project=None)¶: Resolve scope to components iterator.

save_state() → None¶: Save add-on state information.

unit_pre_create(unit, activity_log_id: int | None = None)¶: Event handler before new unit is created.

update_component_state(component, updater: Callable[[dict[str, object]], None]) → None¶: Atomically merge component-scoped add-on state into the shared JSON field.

user()¶: Weblate user used to track changes by this add-on.

Обработчики надстроек получают объекты ORM из модулей weblate.*.models, включая Addon, Component, Translation, Category, Project, Unit, Change и User. Формы настройки надстроек должны быть подклассом weblate.addons.forms.BaseAddonForm.

Вот пример надстройки:

# 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

Документирование операций автоматизации¶

Справочник и сборник рецептов автоматизации использует схему в weblate/automation/schema.py в качестве источника справки. Встроенные действия зарегистрированы в weblate/automation/operations.py, который предоставляет их схемы настроек и результатов, проверку и выполнение. Держите этот реестр внутренним; он не загружает сторонние операции. При добавлении действия установите его заголовок и версию добавления к выпуску Weblate, в котором оно впервые появляется. Сохраняйте эту версию при последующем расширении действия. Блоки управления сохраняют свои метаданные title и x-version-added в схеме рабочего процесса.

Объявите поддерживаемые области действия строк в записи реестра действия. По умолчанию используется component; включите trigger и result, когда выполнение принимает выбор единиц во время выполнения. Передайте область действия в нормализацию, чтобы значения по умолчанию и требования запроса соответствовали выборке. Сообщайте затронутые идентификаторы единиц через сборщик времени выполнения, а не через публичную схему результатов или журнал активности.

Запустите make -C docs update-automation-schema update-automation-docs для обновления загружаемой схемы и справки. Добавляйте пояснения и примеры после соответствующего маркера AUTOGENERATED END в docs/admin/automation.rst. Генератор list_automation сохраняет это ручное содержимое. Держите идентификаторы разделов стабильными, чтобы описания остались привязанными к своим операциям.

Ввод конфигурации дополнения¶

Конфигурация надстройки хранится в JSON-поле Addon.configuration, так что модель хранит сохранённые данные как необработанный JSON. Реализации надстроек могут типизировать свою собственную конфигурацию, параметризуя BaseAddon и BaseAddonForm.

Используйте два класса TypedDict, когда хранимый JSON может отличаться от формы времени выполнения: разрешающий, как правило, total=False, сохранённую конфигурацию для устаревших или отсутствующих значений и полную конфигурацию времени выполнения, возвращаемую normalize_configuration(). Код надстройки во время выполнения должен читать self.configuration или self.get_configuration(), чтобы видеть нормализованные значения по умолчанию вместо необработанного сохранённого JSON.

Для простых надстроек, где сохраняемая и выполняемая формы идентичны, определите один TypedDict и используйте его для обоих параметров типа BaseAddon. Сохраняйте тип возврата serialize_form() формы согласованным с типом сохранённой конфигурации.

Публикация конфигурации дополнения¶

Add-on change history can be visible without add-on management permission. List configuration fields that are safe to publish in the form’s public_configuration_fields attribute. Fields not explicitly listed are kept in the snapshot with a null value and identified as redacted. The default is an empty set so that newly added settings are not published accidentally. Allowlisting a structured field publishes all its nested values. Only list such a field when every value it can contain is safe to publish.

Используйте BaseAddon.get_public_configuration() всякий раз, когда конфигурация раскрывается за пределами доверенного кода управления дополнениями. Внутренние операции, которые намеренно клонируют работающее дополнение, могут продолжать использовать сохранённую конфигурацию.

API дополнений, примонтированных к компоненту¶

Объявите api_name и верните именованные шаблоны URL Django из get_api_urls(). Используйте обычные конвертеры Django и представления DRF. Шаблоны регистрируются для каждого провайдера, включённого в WEBLATE_ADDONS, независимо от того, установлено ли дополнение на компоненте.

Маршруты монтируются по адресу /api/components/<project>/<component>/addons/<api_name>/. Для категоризованных компонентов кодируйте полный путь категории и компонента в сегменте компонента, как для REST API компонента. Используйте api_url установки вместо ручного построения этого URL. Имена API должны содержать от 1 до 64 ASCII-букв, цифр, подчёркиваний или дефисов и быть глобально уникальными среди включённых классов провайдеров. Weblate проверяет эти объявления при запуске, не обращаясь к базе данных, и отклоняет недопустимые или конфликтующие имена. Провайдеры должны объявлять needs_component = True, repo_scope = False и multiple = False. Один и тот же провайдер может быть установлен на многих компонентах, но только один раз на каждом компоненте.

Создайте подкласс weblate.addons.api.InstalledAddonAPIView и задайте его addon_name равным внутреннему имени дополнения провайдера. Базовое представление аутентифицирует запрос, проверяет доступ к компоненту и разрешает установку как self.addon. Отсутствующая или несовместимая установка возвращает HTTP 404. Его permission по умолчанию равно component.edit и проверяется до разбора данных запроса. Парсер JSON по умолчанию ограничивает запросы 5 МиБ, включая запросы без заголовка Content-Length.

Используйте обычную проверку сериализатора DRF в методах представления. Документируйте полный контракт с помощью drf_spectacular.utils.extend_schema и текста справки полей сериализатора: OpenAPI обнаруживает те же представления, что используются для маршрутизации во время выполнения. Обращайтесь к конечным точкам через api:<api_name>:<pattern_name>, указывая project__slug, slug и любые параметры конечной точки. Имена API являются публичными контрактами и должны оставаться стабильными при изменениях реализации. Перезапустите Weblate после изменения регистрации провайдера; тесты, переопределяющие регистрации, должны перестроить свою конфигурацию URL и очистить кеши URL Django.

Существующий API управления /api/addons/<id>/ остаётся доступным. Его поля api_name и api_url только для чтения отражают текущее объявление включённого провайдера. Оба равны null, когда провайдер отключён или несовместим.

Тестирование ресурсов Kotlin SDK¶

Запустите uv run pytest weblate/kotlin_sdk/tests.py с настроенной тестовой средой, чтобы протестировать извлечение, подготовку и публикацию ресурсов, включая API Kotlin SDK.

Тесты бинарного модуля записи, проверка AAPT2 и инструментальные тесты Android поддерживаются в arsc-writer. Инструкции см. в его руководстве по разработке.