Desenvolver extensões¶

Extensões são uma forma de personalizar o fluxo de trabalho de localização no 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.

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.

Parâmetros:

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.

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.

Hooks de extras recebem objetos ORM dos módulos weblate.*.models, incluindo Addon, Component, Translation, Category, Project, Unit, Change, e User. Formulários de configuração de extra devem criar a subclasse weblate.addons.forms.BaseAddonForm.

Aqui está um exemplo de extensão:

# 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


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,
        author: str,
        store_hash: bool,
        activity_log_id: int | None = None,
    ) -> None:
        return

Configuração de tipo de extra¶

A configuração de extra é baseada no campo JSON Addon.configuration, para que o modelo mantenha os dados persistentes na forma de JSON bruto. Implementações de extra agora podem escrever a sua própria configuração ao parametrizar BaseAddon e BaseAddonForm.

Utilize duas classes TypedDict quando o JSON armazenado pode ser diferente da forma em tempo de execução: uma configuração, normalmente total=False, permissiva para legado ou valores em falta, e uma configuração em tempo de execução total devolvida por normalize_configuration(). Código de extras em tempo de execução deve ler self.configuration ou self.get_configuration() para que veja predefinições normalizadas em vez de JSON bruto persistente.

Para extras simples onde as formas armazenadas e de execução são idênticas, define um TypedDict único e utilize-o para ambos os tipos de parâmetro BaseAddon. Mantenha o tipo de retorno do formulário serialize_form() alinhado com o tipo de configuração armazenado.

Publicar configuração de extra¶

Histórico de alterações de extras pode ser visível sem permissão de gestão de extras. Lista campos de configuração os quais são seguros publicar na forma do atributo public_configuration_fields. Campos não explicitamente listados são mantidos no snapshot com um valor nulo e identificados como ocultados. A predefinição é um conjunto vazio para que novas definições adicionadas não sejam publicadas acidentalmente.

Utilize BaseAddon.get_public_configuration() quando a configuração é exposta fora da gestão de código do extra. Operações internas que clonam intencionalmente um extra em funcionamento podem continuar a utilizar a configuração armazenada.