mirror of
https://github.com/WeblateOrg/weblate.git
synced 2026-07-26 14:23:58 +08:00
4b39386b7c
Track pending, skipped, successful, and failed execution paths so logs reflect whether add-ons actually ran.
200 lines
4.9 KiB
ReStructuredText
Vendored
200 lines
4.9 KiB
ReStructuredText
Vendored
..
|
|
Partly generated using ./manage.py list_addons
|
|
|
|
.. _addons:
|
|
|
|
Add-ons
|
|
=======
|
|
|
|
Add-ons provide ways to customize and automate the translation workflow.
|
|
Admins can add and manage add-ons from the :guilabel:`Operations` ↓ :guilabel:`Add-ons` menu of each respective
|
|
translation project or component. Add-ons can be also installed site-wide in :ref:`management-interface`.
|
|
|
|
.. hint::
|
|
|
|
You can also configure add-ons using :ref:`API <addons-api>`,
|
|
:setting:`DEFAULT_ADDONS`, or :wladmin:`install_addon`.
|
|
|
|
Add-ons that opt in to manual triggering can be run from add-on management or using the
|
|
:ref:`API <addons-api>`. Results are recorded in the add-on activity log.
|
|
|
|
.. image:: /screenshots/addons.webp
|
|
|
|
.. include:: /snippets/addon-events-autogenerated.rst
|
|
|
|
.. include:: /snippets/addons-autogenerated.rst
|
|
|
|
Obsolete add-ons
|
|
++++++++++++++++
|
|
|
|
.. _addon-weblate.xml.customize:
|
|
|
|
Customize XML output
|
|
--------------------
|
|
|
|
.. versionadded:: 4.15
|
|
|
|
.. versionremoved:: 5.13 Replaced by :ref:`file_format_params`.
|
|
|
|
.. _addon-weblate.yaml.customize:
|
|
|
|
Customize YAML output
|
|
---------------------
|
|
|
|
.. versionremoved:: 5.13 Replaced by :ref:`file_format_params`.
|
|
|
|
.. include:: /snippets/addon-parameters-autogenerated.rst
|
|
|
|
|
|
Customizing list of add-ons
|
|
+++++++++++++++++++++++++++
|
|
|
|
The list of add-ons is configured by :setting:`WEBLATE_ADDONS`.
|
|
To add another add-on, simply include the absolute class name in this setting.
|
|
|
|
|
|
.. _own-addon:
|
|
|
|
Writing add-on
|
|
++++++++++++++
|
|
|
|
You can write your own add-ons too, create a subclass of
|
|
:class:`weblate.addons.base.BaseAddon` to define the add-on metadata, and
|
|
then implement a callback to do the processing.
|
|
|
|
.. seealso::
|
|
|
|
:doc:`../contributing/addons`
|
|
|
|
.. _addon-script:
|
|
|
|
Executing scripts from add-on
|
|
+++++++++++++++++++++++++++++
|
|
|
|
Add-ons can also be used to execute external scripts. This used to be
|
|
integrated in Weblate, but now you have to write some code to wrap your
|
|
script with an add-on.
|
|
|
|
.. literalinclude:: ../../weblate/addons/example_pre.py
|
|
:language: python
|
|
|
|
For installation instructions see :ref:`custom-addon-modules`.
|
|
|
|
The script is executed with the current directory set to the root of the VCS repository
|
|
for any given component.
|
|
|
|
Additionally, the following environment variables are available:
|
|
|
|
.. envvar:: WL_VCS
|
|
|
|
Version control system used.
|
|
|
|
.. envvar:: WL_REPO
|
|
|
|
Upstream repository URL.
|
|
|
|
.. envvar:: WL_PATH
|
|
|
|
Absolute path to VCS repository.
|
|
|
|
.. envvar:: WL_BRANCH
|
|
|
|
Repository branch configured in the current component.
|
|
|
|
.. envvar:: WL_FILEMASK
|
|
|
|
File mask for current component.
|
|
|
|
.. envvar:: WL_TEMPLATE
|
|
|
|
Filename of template for monolingual translations (can be empty).
|
|
|
|
.. envvar:: WL_NEW_BASE
|
|
|
|
Filename of the file used for creating new translations (can be
|
|
empty).
|
|
|
|
.. envvar:: WL_FILE_FORMAT
|
|
|
|
File format used in current component.
|
|
|
|
.. envvar:: WL_LANGUAGE
|
|
|
|
Language of currently processed translation (not available for
|
|
component-level hooks).
|
|
|
|
.. envvar:: WL_PREVIOUS_HEAD
|
|
|
|
Previous HEAD after update (only available after running the post-update hook).
|
|
|
|
.. envvar:: WL_COMPONENT_SLUG
|
|
|
|
Component slug used to construct URL.
|
|
|
|
.. envvar:: WL_PROJECT_SLUG
|
|
|
|
Project slug used to construct URL.
|
|
|
|
.. envvar:: WL_COMPONENT_NAME
|
|
|
|
Component name.
|
|
|
|
.. envvar:: WL_PROJECT_NAME
|
|
|
|
Project name.
|
|
|
|
.. envvar:: WL_COMPONENT_URL
|
|
|
|
Component URL.
|
|
|
|
.. envvar:: WL_ENGAGE_URL
|
|
|
|
Project engage URL.
|
|
|
|
.. seealso::
|
|
|
|
:ref:`component`
|
|
|
|
Post-update repository processing
|
|
---------------------------------
|
|
|
|
Can be used to update translation files when the VCS upstream source changes.
|
|
To achieve this, please remember Weblate only sees files committed to the VCS,
|
|
so you need to commit changes as a part of the script.
|
|
|
|
For example with Gulp you can do it using following code:
|
|
|
|
.. code-block:: sh
|
|
|
|
#! /bin/sh
|
|
gulp --gulpfile gulp-i18n-extract.js
|
|
git commit -m 'Update source strings' src/languages/en.lang.json
|
|
|
|
|
|
Pre-commit processing of translations
|
|
-------------------------------------
|
|
|
|
Use the commit script to automatically change a translation before it is committed
|
|
to the repository.
|
|
|
|
It is passed as a single parameter consisting of the filename of a current translation.
|
|
|
|
|
|
.. _addon-activity-logging:
|
|
|
|
Add-on activity logging
|
|
-----------------------
|
|
|
|
Add-on activity log keeps track of the add-on execution and can be used to
|
|
keep track of add-on activity.
|
|
|
|
Each entry records whether processing is pending, successful, failed, or
|
|
skipped. Skipped entries include the reason the add-on did not run, such as an
|
|
incompatible component, no relevant changes, or a configured schedule that is
|
|
not due yet. A successful entry can still mean that the add-on checked its
|
|
inputs but found nothing to change.
|
|
|
|
For scope-wide add-ons that process components independently, the activity log
|
|
contains a separate entry for each component.
|
|
|
|
The logs can be pruned after a certain time interval by configuring the :setting:`ADDON_ACTIVITY_LOG_EXPIRY`.
|
