# Add-ons
Add-ons provide ways to customize and automate the translation workflow.
Admins can add and manage add-ons from the Operations ↓ Add-ons menu of each respective
translation project or component. Add-ons can be also installed site-wide in [Management interface](https://docs.weblate.org/en/weblate-2026.10/admin/admin.md#management-interface).
#### HINT
You can also configure add-ons using [API](https://docs.weblate.org/en/weblate-2026.10/api.md#addons-api),
[`DEFAULT_ADDONS`](https://docs.weblate.org/en/weblate-2026.10/admin/config.md#std-setting-DEFAULT_ADDONS), or [`install_addon`](https://docs.weblate.org/en/weblate-2026.10/admin/management.md#weblate-admin-install_addon).
Add-ons that opt in to manual triggering can be run from add-on management or using the
[API](https://docs.weblate.org/en/weblate-2026.10/api.md#addons-api). Results are recorded in the add-on activity log.
Add-ons that expose a component API show its base URL on the add-on’s
API tab, alongside a link to the API root.
Add-ons are persistent administrative configuration. They run with their
service identity in the scope where they are installed, rather than repeatedly
using the permissions of the administrator who configured them. This ensures
that equally authorized administrators see and save the same configuration,
and that saving an unrelated change does not silently alter the add-on’s input
scope. Removing or disabling the configuring administrator does not disable the
add-on.
Project and category add-ons therefore include compatible restricted components
in that scope. A component add-on can use inputs outside its destination
component when documented by that add-on. Automatic translation determines its
source components as follows:
* Direct automatic-translation actions use the acting user’s component access.
* A saved automatic-translation add-on uses its persistent administrative
scope. Compatible components in the target project are eligible, including
restricted components.
* Components in another project are eligible when that project contributes to
shared translation memory. This includes restricted components even though
they do not create shared translation-memory entries; the add-on reads the
explicitly selected component as an administrative input instead.
Restricted components remain filtered from ordinary listings and direct access.
Grant add-on management permissions only to users trusted with the add-on’s
complete input and effect scope. See [Scope of teams](https://docs.weblate.org/en/weblate-2026.10/admin/access.md#perm-check) and
[Restricted access](https://docs.weblate.org/en/weblate-2026.10/admin/projects.md#component-restricted).
## Events that trigger add-ons
### Add-on installation
Triggered when add-on is being installed.
### Component update
Triggered whenever a change happens in a component such as:
* Strings are changed in the repository.
* A string is added.
* A new translation is added.
### Daily
Triggered daily, but add-ons usually split the daily load between components depending on [`BACKGROUND_TASKS`](https://docs.weblate.org/en/weblate-2026.10/admin/config.md#std-setting-BACKGROUND_TASKS).
### Event change
Triggered after a Change event is created.
### Manual trigger
Triggered when an add-on is run manually from add-on management or the API.
### Repository post-add
Triggered just after the new translation is added and committed.
### Repository post-commit
Triggered just after the changes are committed.
### Repository post-push
Triggered just after the repository is pushed upstream.
### Repository post-remove
Triggered just after a translation is removed.
### Repository post-update
Triggered whenever new changes are pulled from the upstream repository.
### Repository pre-commit
Triggered just before the changes are committed.
### Repository pre-push
Triggered just before the repository is pushed upstream.
### Repository pre-update
Triggered just before the repository update is attempted.
### Unit post-save
Triggered just after the string is saved.
### Unit post-sync
Triggered after the string is synchronized with the VCS.
### Unit pre-create
Triggered just after the newly created string is saved.
## Built-in add-ons
### AI quality evaluation
* **Add-on ID:**
`weblate.ai.quality`
* **Configuration:**
| `service` | Evaluation service | #### Available choices:
| `anthropic` | Anthropic |
|----------------|--------------|
| `openai` | OpenAI |
| `mistral` | Mistral |
| `ollama` | Ollama |
| `azure-openai` | Azure OpenAI | |
|-------------|------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `q` | Query | |
| `interval` | Evaluation frequency | #### Available choices:
| `disabled` | Disabled |
|--------------|------------|
| `daily` | Daily |
| `weekly` | Weekly |
| `monthly` | Monthly | |
| `on_change` | Evaluate translation changes | |
| `on_update` | Evaluate repository updates | |
* **Triggers:**
[Add-on installation](#addon-event-add-on-installation), [Component update](#addon-event-component-update), [Daily](#addon-event-daily), [Event change](#addon-event-event-change), [Manual trigger](#addon-event-manual-trigger)
Evaluates existing translations using an LLM and records quality checks.
This add-on evaluates existing translations using
an LLM service configured under [Automatic suggestions](https://docs.weblate.org/en/weblate-2026.10/user/translating.md#machine-translation). It does not generate
suggestions or change translations. Choose an Evaluation service from
the configured LLM services; credentials and project overrides are reused.
The Query selects strings using the normal search syntax. By default,
translated strings are selected. Source strings, read-only strings, and glossary
entries are excluded. Each request includes all translation plural forms, source
text, language information, string context, glossary terms, placeholders, and
configured translation instructions. This data is sent to the selected provider.
Requests group strings from the same translation in file order, using the
service’s automatic translation batch size (currently 20 strings for built-in
LLM services). All plural forms of a string stay together. Related strings share
context, allowing the evaluator to check meaning and terminology across the
batch. Batching reduces the number of provider requests for scheduled, manual,
and change-triggered runs; it does not skip unchanged strings.
Evaluation frequency defaults to weekly. Daily and monthly schedules
are also available; disabled turns off scheduled evaluation. Background processing
must be enabled. A successful full run starts the next interval. Manual runs
bypass the interval. Enable Evaluate translation changes or
Evaluate repository updates to additionally evaluate after those events.
Installation does not immediately contact the provider. Each run can incur provider
costs, including reevaluation of unchanged translations.
Evaluation runs in background tasks, with results and failure counts recorded in
the existing add-on activity log. Failed requests retain existing valid findings
and are tried again only by a subsequent run. Evaluation shares the service’s
automatic translation cooldown: rate-limit responses activate it, and batches
are skipped while it is active. More specific installations take
precedence: component, nearest category, project, then site-wide.
Findings appear as standard checks for accuracy, fluency, terminology, style, and
formatting. Each finding includes a minor, major, or critical severity and an
explanation. Multiple findings in one category share a check, so ignoring that
check ignores the whole category for the string. Existing search filters and API
search work, for example `check:ai_accuracy`. Translation flags such as
`ignore-ai-accuracy` disable a category; `ignore-all-checks` disables all checks.
Changing the source or translation removes outdated findings. Results received
after any source or translation in their batch changes are discarded for the
whole batch. A failed or malformed response also leaves existing findings for
the whole batch unchanged; other batches can still complete. Incomplete runs do
not advance the scheduled evaluation date. Reevaluation of unchanged content
preserves ignored categories, and a successful evaluation removes categories
that no longer have findings. Removing or reconfiguring the add-on clears its
findings. Evaluator metadata is internal and cannot be edited through the API;
the add-on configuration uses the existing [Add-ons](https://docs.weblate.org/en/weblate-2026.10/api.md#addons-api) permissions and
validation.
### Automation
#### Versionadded
Added in version 2026.10.
* **Add-on ID:**
`weblate.automation.automation`
* **Configuration:**
| `workflow` | Workflow | Enter an automation definition as YAML or JSON. |
|--------------|------------|---------------------------------------------------|
* **Triggers:**
[Component update](#addon-event-component-update), [Daily](#addon-event-daily), [Event change](#addon-event-event-change), [Manual trigger](#addon-event-manual-trigger), [Repository post-commit](#addon-event-repository-post-commit), [Repository post-push](#addon-event-repository-post-push), [Repository post-update](#addon-event-repository-post-update)
Runs ordered translation operations with conditions and branches.
Install this add-on on a component, category, project, or site. Inherited
instances run separately for each component. Multiple instances can be installed.
Configuring, previewing, and running an automation requires the usual add-on
management permission. Saving its configuration does not execute it.
Enter YAML or JSON in Workflow. Use Preview without changes
to validate it and inspect planned actions, then Run now for real
execution. Results appear in the add-on activity log.
#### SEE ALSO
* [Workflow definition](https://docs.weblate.org/en/weblate-2026.10/admin/automation.md#automation-workflows) for the script definition and reference.
* [Cookbook](https://docs.weblate.org/en/weblate-2026.10/admin/automation.md#automation-cookbook) for complete examples.
* [Apply translation memory before machine translation](https://docs.weblate.org/en/weblate-2026.10/admin/automation.md#automation-translation-ordering) for translation memory before machine translation.
### Automatic translation
* **Add-on ID:**
`weblate.autotranslate.autotranslate`
* **Configuration:**
| `mode` | Automatic translation mode | #### Available choices:
| `suggest` | Add as suggestion |
|-------------|-----------------------------|
| `translate` | Add as translation |
| `fuzzy` | Add as “Needing edit” |
| `approved` | Add as approved translation | |
|---------------|----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `q` | Query | Please note that translating all strings will discard all existing translations. |
| `auto_source` | Source of automated translations | #### Available choices:
| `others` | Other translation components |
|------------|--------------------------------|
| `mt` | Machine translation | |
| `component` | Component | Enter a source component ID. With 30 or more eligible source components, a project/component path is also accepted. In that case, component and project operations also accept a component slug from the target project. Leave blank to use eligible components from each target component’s project. |
| `engines` | Machine translation engines | [Machine translation engines](#addon-choice-engines) |
| `threshold` | Score threshold | |
* **Triggers:**
[Add-on installation](#addon-event-add-on-installation), [Component update](#addon-event-component-update), [Daily](#addon-event-daily), [Event change](#addon-event-event-change)
Automatically translates strings using machine translation or other components.
To control translation order, use the [Automation](#addon-weblate-automation-automation)
add-on with a separate action for each pass. Follow the
[Apply translation memory before machine translation](https://docs.weblate.org/en/weblate-2026.10/admin/automation.md#automation-translation-ordering) cookbook example to apply local translation
memory first and send only the remaining strings to a machine translation service.
Selecting multiple engines here uses [Priority of machine translation and translation memory services](https://docs.weblate.org/en/weblate-2026.10/admin/machine.md#mt-translation-services-priority);
installation order of separate add-ons does not define an execution sequence.
#### SEE ALSO
* [Automatic translation](https://docs.weblate.org/en/weblate-2026.10/user/translating.md#auto-translation)
* [Keeping translations same across components](https://docs.weblate.org/en/weblate-2026.10/admin/continuous.md#translation-consistency)
* [Priority of machine translation and translation memory services](https://docs.weblate.org/en/weblate-2026.10/admin/machine.md#mt-translation-services-priority)
* [Searching for strings](https://docs.weblate.org/en/weblate-2026.10/user/search.md#search-strings)
### JavaScript localization CDN
#### Versionadded
Added in version 4.2.
* **Add-on ID:**
`weblate.cdn.cdnjs`
* **Configuration:**
| `threshold` | Translation threshold | The percentage of translated strings that must be present for translation to be included. |
|----------------|---------------------------------|---------------------------------------------------------------------------------------------|
| `css_selector` | CSS selector | CSS selector to detect localizable elements. |
| `cookie_name` | Language cookie name | Name of cookie which stores language preference. |
| `files` | Extract strings from HTML files | List of filenames in current repository or remote URLs to parse for translatable strings. |
* **Triggers:**
[Add-on installation](#addon-event-add-on-installation), [Daily](#addon-event-daily), [Repository post-commit](#addon-event-repository-post-commit), [Repository post-remove](#addon-event-repository-post-remove), [Repository post-update](#addon-event-repository-post-update)
Publishes translations into content delivery network for use in JavaScript or
HTML localization.
Can be used to localize static HTML pages, or
to load localization in the JavaScript code.
Generates a unique URL for your component you can include in
HTML pages to localize them. See [Translating HTML and JavaScript using Weblate CDN](https://docs.weblate.org/en/weblate-2026.10/devel/html.md#weblate-cdn) for more details.
#### NOTE
This add-on requires additional configuration on the Weblate server.
[`LOCALIZE_CDN_PATH`](https://docs.weblate.org/en/weblate-2026.10/admin/config.md#std-setting-LOCALIZE_CDN_PATH) configures where generated files will be
written (on a filesystem), and [`LOCALIZE_CDN_URL`](https://docs.weblate.org/en/weblate-2026.10/admin/config.md#std-setting-LOCALIZE_CDN_URL) defines where
they will be served (URL). Serving of the files is not done by Weblate and
has to be set up externally (typically using a CDN service).
This add-on is configured on Hosted Weblate and serves the files
via `https://weblate-cdn.com/`.
#### SEE ALSO
* [Configuring Weblate CDN add-on](https://docs.weblate.org/en/weblate-2026.10/devel/html.md#cdn-addon-config)
* [Translating HTML and JavaScript using Weblate CDN](https://docs.weblate.org/en/weblate-2026.10/devel/html.md#weblate-cdn)
* [Localization CDN](https://docs.weblate.org/en/weblate-2026.10/admin/optionals.md#cdn-server-security)
* [String extraction for Weblate CDN](https://docs.weblate.org/en/weblate-2026.10/devel/html.md#cdn-addon-extract)
* [HTML localization using Weblate CDN](https://docs.weblate.org/en/weblate-2026.10/devel/html.md#cdn-addon-html)
### Translation files CDN
#### Versionadded
Added in version 2026.5.
* **Add-on ID:**
`weblate.cdn.files`
* **Configuration:**
This add-on has no configuration.
* **Triggers:**
[Add-on installation](#addon-event-add-on-installation), [Component update](#addon-event-component-update), [Repository post-commit](#addon-event-repository-post-commit), [Repository post-remove](#addon-event-repository-post-remove), [Repository post-update](#addon-event-repository-post-update)
Publishes translation files into a content delivery network.
Publishes translation files without converting them to another format. Files
are written below the add-on specific CDN directory and served from
`LOCALIZE_CDN_URL//`. Single-file translations use the language
code and original file extension, for example `cs.json` or `de.po`.
Multi-file translations are served below the language code using paths relative
to the translation directory. Monolingual components include the source
language file, while bilingual components publish only target-language files.
See [Localization CDN](https://docs.weblate.org/en/weblate-2026.10/admin/optionals.md#cdn-server-security) for secure serving guidance.
### Kotlin SDK CDN
#### Versionadded
Added in version 2026.10.
* **Add-on ID:**
`weblate.cdn.kotlin`
* **Configuration:**
| `maximum_age` | Maximum build age (days) | Retires builds this many days after their first registration. Re-registering a build does not extend its age. |
|--------------------|----------------------------|---------------------------------------------------------------------------------------------------------------------------|
| `maximum_versions` | Maximum retained versions | Limits retained builds across all package names. A build is retired when either this limit or the maximum age is reached. |
* **Triggers:**
[Add-on installation](#addon-event-add-on-installation), [Component update](#addon-event-component-update), [Daily](#addon-event-daily), [Repository post-commit](#addon-event-repository-post-commit), [Repository post-remove](#addon-event-repository-post-remove), [Repository post-update](#addon-event-repository-post-update)
Publishes Android string and plural resources for registered Kotlin SDK builds.
#### WARNING
The Kotlin SDK API is in beta. No compatibility is guaranteed until the
final Kotlin SDK is released. Endpoints, build metadata, CDN manifests, and
generated resource formats may change without backward compatibility.
Install Kotlin SDK CDN on an Android string-resource component to
publish translations for builds registered by the Kotlin SDK. Configure
[`LOCALIZE_CDN_URL`](https://docs.weblate.org/en/weblate-2026.10/admin/config.md#std-setting-LOCALIZE_CDN_URL) and [`LOCALIZE_CDN_PATH`](https://docs.weblate.org/en/weblate-2026.10/admin/config.md#std-setting-LOCALIZE_CDN_PATH) first. CDN output is
public, including translations from private components. Manifests expose the
application package name and version code. ARSC files expose published resource
names and their submitted IDs alongside translated text. Do not treat the
uploaded resource mapping as confidential; enable publication only when this
disclosure is intended. Registration and status API access remains permission-controlled.
Copy the Gradle plugin configuration from the add-on configuration page. It
includes the Weblate server URL, public CDN URL, project slug, and component
path (with any category path URL-encoded). Replace the placeholder with a
project-scoped API token whose permissions allow editing the component. Project
administrators can create one in the project’s API access tab; see
[Per-project access tokens](https://docs.weblate.org/en/weblate-2026.10/admin/access.md#project-api).
Keep that token in the build environment, not in the application. The add-on’s
API tab shows the API base URL; submit build metadata to its `builds/`
endpoint. See
[Kotlin SDK builds](https://docs.weblate.org/en/weblate-2026.10/api.md#kotlin-sdk-build-api) for the request and response format.
For Gradle plugin and library setup, see the [Kotlin SDK repository](https://github.com/WeblateOrg/kotlin-sdk/).
The add-on matches resource names and types from registered builds to current
component translations. Strings, plurals, and Android styled text are supported.
String arrays and resource references are not generated. Untranslated entries,
read-only entries, and incomplete plural resources are omitted; applications
retain their bundled values. Unsupported styling fails publication; the previous
successful publication remains available.
Resource IDs must describe the final installed build. Uploading an identical
mapping again is harmless; a different mapping for the same package and version
is rejected. Old builds receive current translations by name, including after
source text or formatting arguments change. Maintainers are responsible for
compatibility with older application code.
#### Lifecycle settings
* Maximum build age (days) defaults to 365 and accepts 1 through 730,
measured from the first registration. Repeated uploads do not extend it.
* Maximum retained versions defaults to 20 and accepts 1 through 100,
counted across all package names. One additional unpublished replacement is
allowed. New registrations can retire older unpublished replacements. Published
builds are retired for this limit only after a replacement is published.
Failed replacements preserve existing publications; maximum-age expiry still
applies independently.
Either limit retires a build and immediately clears its metadata. Lightweight
retired records are deleted on cleanup after 24 hours and successful manifest
removal; their package/version identifiers can then be registered again.
Failed or interrupted manifest removals are retried hourly. Until removal
succeeds, the registration and its referenced artifacts are retained, and the
files may remain publicly accessible. Resource mappings are immutable only while
their registration records remain.
Each add-on permits at most 1000 registration records, including retired records.
New registrations exceeding this limit return HTTP 409 until cleanup frees
capacity; identical retries remain accepted. Metadata is bounded by the 5 MiB
upload limit and maximum retained version count plus one replacement, without a
separate byte quota.
Limits are enforced during registration and scheduled cleanup.
Superseded artifacts are deleted on cleanup after a fixed 24-hour window. All
artifact files, including superseded files and incomplete publication output,
count towards hard limits of 5 GiB and 10000 files per add-on. The larger artifact
allowance accommodates translated text and multiple locales; it does not
guarantee capacity for every locale or build combination. Shared artifacts
count only once. Publications exceeding either limit fail before writing new
artifacts and preserve the previous manifest. Neither the window nor these
limits are configurable. Limit manifest caching as described below.
Compilation stages one locale at a time on disk. A per-locale conservative
encoded text and styling estimate exceeding 64 MiB fails publication.
Preparation additionally requires up to 5 GiB of temporary disk space per
publication job, separate from the published artifact allowance. Temporary
files contain staged ARSC output, shared by versions with identical resource mappings.
They are stored below [`LOCALIZE_CDN_PATH`](https://docs.weblate.org/en/weblate-2026.10/admin/config.md#std-setting-LOCALIZE_CDN_PATH). Configure the server to
deny access to `.kotlin-sdk-staging` as described in
[Localization CDN](https://docs.weblate.org/en/weblate-2026.10/admin/optionals.md#cdn-server-security) before enabling this add-on.
Manifest replacement follows the database commit. Failed or interrupted writes
are retried by subsequent publication jobs, with artifacts for both the old and
pending manifest protected until replacement succeeds.
Uninstalling the add-on attempts to remove its published files from the CDN origin
immediately. Failed or interrupted removals are retried hourly; files may remain
publicly accessible until cleanup succeeds. Removal does not revoke copies already
cached or downloaded by clients.
Publication and cleanup run asynchronously after build registration, component
updates, translation commits and removals, and during daily add-on processing.
Failures appear in the add-on activity log and registration status. Previous
successful publications remain available when replacement generation fails.
If the component stops using the Android resource format, hourly maintenance
retires its publications. The normal artifact retention window still applies.
#### CDN client contract
Each build has a stable manifest at
`///manifest.json`. The version 1 manifest
contains `schemaVersion`, `packageName`, `versionCode`, and `locales`.
Locale keys are Weblate language codes. Each locale contains a relative `url`,
`sha256`, and byte `size` for its ARSC artifact. Resolve relative URLs against
the manifest URL. Artifact contents do not change after publication.
The manifest has a [`JSON Schema`](https://docs.weblate.org/en/weblate-2026.10/admin/_downloads/3f1cd8a80d26f6e0da13555125072237/weblate-kotlin-sdk-manifest.schema.json).
Configure the CDN origin to cache manifests for at most one hour (for example,
`Cache-Control: public, max-age=3600`), and artifact files with
`Cache-Control: public, max-age=31536000, immutable`. Artifact files may use
`application/octet-stream`. Configure these headers on the CDN server.
Translation updates and retirements can take up to one hour to reach clients.
Use `Cache-Control: no-cache` when immediate revalidation is preferred.
The fixed 24-hour artifact retention window exceeds the manifest cache lifetime.
The Kotlin SDK should validate artifact length and hash, cache successful
downloads locally, and load them with Android’s resources-loader API on API 30
or newer. A missing manifest, missing locale, or download failure must preserve
bundled resources. Retired manifests return 404 at the origin; cached copies can
remain usable until they expire. Hashes detect corrupted or
mismatched content; authentication relies on HTTPS and the configured CDN.
### Remove blank strings
#### Versionadded
Added in version 4.4.
* **Add-on ID:**
`weblate.cleanup.blank`
* **Configuration:**
This add-on has no configuration.
* **Triggers:**
[Add-on installation](#addon-event-add-on-installation), [Repository post-commit](#addon-event-repository-post-commit), [Repository post-update](#addon-event-repository-post-update)
Removes strings without a translation from translation files.
Use this to not have any empty strings in translation files (for
example if your localization library displays them as missing instead
of falling back to the source string).
#### SEE ALSO
[Does Weblate update translation files besides translations?](https://docs.weblate.org/en/weblate-2026.10/faq.md#faq-cleanup)
### Cleanup translation files
* **Add-on ID:**
`weblate.cleanup.generic`
* **Configuration:**
This add-on has no configuration.
* **Triggers:**
[Add-on installation](#addon-event-add-on-installation), [Repository post-update](#addon-event-repository-post-update), [Repository pre-commit](#addon-event-repository-pre-commit)
Update all translation files to match the monolingual base file. For most file
formats, this means removing stale translation keys no longer present in the
base file.
For formats containing additional content besides translation strings (such as
[HTML files](https://docs.weblate.org/en/weblate-2026.10/formats/html.md#html), [Windows RC files](https://docs.weblate.org/en/weblate-2026.10/formats/winrc.md#winrc), or [OpenDocument Format](https://docs.weblate.org/en/weblate-2026.10/formats/odf.md#odf)) this also brings the translation file
in sync with the base file.
For a one-time cleanup of a single translation file, use
Cleanup unused in [Repository maintenance](https://docs.weblate.org/en/weblate-2026.10/admin/continuous.md#repository-maintenance) on that translation
instead of installing the add-on.
#### SEE ALSO
[Does Weblate update translation files besides translations?](https://docs.weblate.org/en/weblate-2026.10/faq.md#faq-cleanup)
### Add missing languages
* **Add-on ID:**
`weblate.consistency.languages`
* **Configuration:**
This add-on has no configuration.
* **Triggers:**
[Add-on installation](#addon-event-add-on-installation), [Daily](#addon-event-daily), [Repository post-add](#addon-event-repository-post-add)
Ensures a consistent set of languages is used for all components within a
project.
#### NOTE
The components shared from other projects are not considered in this.
Missing languages are checked once every 24 hours, and when new languages
are added in Weblate.
Unlike most others, this add-on affects the whole project.
#### HINT
Auto-translate the newly added strings with
[Automatic translation](#addon-weblate-autotranslate-autotranslate).
### Component discovery
* **Add-on ID:**
`weblate.discovery.discovery`
* **Configuration:**
| `match` | Regular expression to match translation files against | The regular expression must define a named group for component. Also define a named group for language when matching translation files. When the file mask is set, omit language and match the monolingual base or new base file instead. |
|-------------------------|-----------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `file_format` | File format | [File format](#addon-choice-file-format) |
| `name_template` | Customize the component name | Use Django template syntax. This template must include {{ component }}. |
| `base_file_template` | Define the monolingual base filename | Leave empty for bilingual translation files. When set, this template must include {{ component }}. |
| `new_base_template` | Define the base file for new translations | Filename of file used for creating new translations. For gettext choose .pot file. This template must include {{ component }}. |
| `intermediate_template` | Intermediate language file | Filename of intermediate translation file. In most cases this is a translation file provided by developers and is used when creating actual source strings. This template must include {{ component }}. |
| `filemask_template` | Define the file mask | Leave empty to match translation files directly. When set, discovery matches the monolingual base or new base file and uses this template as the file mask. Include a language wildcard and {{ component }}, for example locale/ */{{ component }}.po or docs/{{ component }}_*.md. |
| `language_regex` | Language filter | Regular expression to filter translation files against when scanning for file mask. |
| `copy_addons` | Clone add-ons from the main component to the newly created ones | |
| `remove` | Remove components for inexistent files | |
* **Triggers:**
[Add-on installation](#addon-event-add-on-installation), [Repository post-update](#addon-event-repository-post-update)
Automatically adds or removes project components based on file changes in the
version control system.
The matching is done using regular expressions
enabling complex configuration, but some knowledge is required to do so.
Usually the regular expression to match translation files has to contain two named
groups to match component and language. When creating components from a monolingual
base or new base file, omit the language group and match that source file instead.
All named groups in the regular expression can be used as variables in the template
fields.
#### Discovery requirements
To discover a component successfully, the configuration has to do all of the following:
* The regular expression must define a `component` named group. Matching
translation files also requires a `language` named group.
* Template fields used to name or locate per-component files must include
`{{ component }}`, so the rendered value actually changes for each discovered
component.
* For monolingual formats, the component must contain a file matching
`base_file_template` and at least one translation file matching `match`,
unless you set the file mask (see below).
#### Discovering components without translation files
Set Define the file mask to discover components from a
monolingual base or new base file alone, even when no translation files exist yet.
In that mode:
* Configure Regular expression to match translation files against to
match the monolingual base or new base file, and omit the `language` group.
Keep full control over the `component` capture, for example
`locale/(?P[^/]+)\.pot` or `docs/(?P[^/_]+)\.md`.
* Fill Define the file mask with a path that includes both a
language wildcard and `{{ component }}`, for example
`locale/*/{{ component }}.po` or `docs/{{ component }}_*.md`.
* Keep using the other filename templates with any named groups from the match
expression.
#### Worked example: `news_.md`
This is a common filename-based language variant layout:
* `docs/news_en.md`
* `docs/news_cs.md`
* `docs/guide_en.md`
Use the Filename-based language variants preset for a starting point,
then choose the matching file format and review the populated values.
Regular expression:
: `(?:(?P.*/))?(?P.+?)_(?P[A-Za-z]{2,3}(?:[_-][A-Za-z0-9]+)*)\.(?P[^/.]+)`
Component name:
: `{{ component }}`
Discovered file masks:
: - `docs/news_*.md`
- `docs/guide_*.md`
In this example, `{{ component }}` resolves to the basename before the language
suffix, so `docs/news_en.md`, `docs/news_pt_BR.md`, and
`docs/news_pt-BR.md` all become the `news` component.
You can use Django template markup in all filename fields, for example:
`{{ component }}`
: Component name parsed from the `component` match group
`{{ component|title }}`
: Component filename with upper case first letter
`{{ path }}: {{ component }}`
: Custom match group from the regular expression
Once you hit Save, a preview of matching components will be presented,
from where you can check whether the configuration actually matches your needs:
#### Component discovery examples
The worked example above covers the most common filename-based variant layout.
The following examples show other repository structures you can match.
##### One folder per language
One folder per language containing translation files for components.
Regular expression:
: `(?P[^/.]*)/(?P[^/]*)\.po`
Matching files:
: - `cs/application.po`
- `cs/website.po`
- `de/application.po`
- `de/website.po`
##### Gettext locales layout
Usual structure for storing gettext PO files.
Regular expression:
: `locale/(?P[^/.]*)/LC_MESSAGES/(?P[^/]*)\.po`
Matching files:
: - `locale/cs/LC_MESSAGES/application.po`
- `locale/cs/LC_MESSAGES/website.po`
- `locale/de/LC_MESSAGES/application.po`
- `locale/de/LC_MESSAGES/website.po`
##### Complex filenames
Using both component and language name within filename.
Regular expression:
: `src/locale/(?P[^/]*)\.(?P[^/.]*)\.po`
Matching files:
: - `src/locale/application.cs.po`
- `src/locale/website.cs.po`
- `src/locale/application.de.po`
- `src/locale/website.de.po`
##### Repeated language code
Using language in both path and filename.
Regular expression:
: `locale/(?P[^/.]*)/(?P[^/]*)/(?P=language)\.po`
Matching files:
: - `locale/cs/application/cs.po`
- `locale/cs/website/cs.po`
- `locale/de/application/de.po`
- `locale/de/website/de.po`
##### Split Android strings
Android resource strings, split into several files.
Regular expression:
: `res/values-(?P[^/.]*)/strings-(?P[^/]*)\.xml`
Matching files:
: - `res/values-cs/strings-about.xml`
- `res/values-cs/strings-help.xml`
- `res/values-de/strings-about.xml`
- `res/values-de/strings-help.xml`
##### Matching multiple paths
Multi-module Maven project with Java properties translations.
Regular expression:
: `(?P.+/)(?P[^/]*)/src/main/resources/ApplicationResources_(?P[^/.]*)\.properties`
Component name:
: `{{ originalHierarchy }}: {{ component }}`
Matching files:
: - `parent/module1/submodule/src/main/resources/ApplicationResources_fr.properties`
- `parent/module1/submodule/src/main/resources/ApplicationResource_es.properties`
- `parent/module2/src/main/resources/ApplicationResource_de.properties`
- `parent/module2/src/main/resources/ApplicationResource_ro.properties`
#### HINT
Component discovery add-on uses [Weblate internal URLs](https://docs.weblate.org/en/weblate-2026.10/vcs.md#internal-urls). It’s a convenient way to share
VCS setup between multiple components. Linked components use the local repository of
the main component set up by filling `weblate://project/main-component`
into the [Source code repository](https://docs.weblate.org/en/weblate-2026.10/admin/projects.md#component-repo) field (in Operations ↓ Settings ↓
Version control system) of each respective component.
This saves time with configuration and system resources too.
#### HINT
Ensure the new component contains the full set of translatable languages with
[Add missing languages](#addon-weblate-consistency-languages).
#### SEE ALSO
* [Template markup](https://docs.weblate.org/en/weblate-2026.10/admin/projects.md#markup)
* [`import_project`](https://docs.weblate.org/en/weblate-2026.10/admin/management.md#weblate-admin-import_project)
### Fedora Messaging
#### Versionadded
Added in version 5.15.
* **Add-on ID:**
`weblate.fedora_messaging.publish`
* **Configuration:**
| `amqp_url` | AMQP broker URL | The AMQP broker URL to connect to. |
|-----------------------|-----------------------------|------------------------------------------------------------------------------------------------------------------------------------|
| `topic_prefix` | Topic prefix | Optional prefix to prepend to generated message topics. |
| `publish_timeout` | Publish timeout | How many seconds to wait for the broker delivery acknowledgement. |
| `connection_attempts` | Connection attempts | How many times to try connecting to the broker. |
| `retry_delay` | Retry delay | How many seconds to wait between connection attempts. |
| `ca_cert` | CA certificate bundle (PEM) | Paste only PEM certificate blocks, each starting with “—–BEGIN CERTIFICATE—–” and ending with “—–END CERTIFICATE—–“. |
| `client_key` | Client private key (PEM) | Paste a single unencrypted PEM private key block. Encrypted private keys are not supported. |
| `client_cert` | Client certificate (PEM) | Paste only the PEM certificate block starting with “—–BEGIN CERTIFICATE—–”; do not paste the output from “openssl x509 -text”. |
| `event_filter` | Change events to trigger | Choose which change events should trigger this add-on.
[Change events to trigger](#addon-choice-event-filter) |
| `events` | Selected change events | [Selected change events](#addon-choice-events) |
* **Triggers:**
[Event change](#addon-event-event-change)
Sends notifications to a Fedora Messaging compatible AMQP exchange.
Fedora Messaging is AMQP-based publisher for all changes happening in Weblate.
You can hook additional services on changes happening in Weblate using this.
#### Message topic
All messages have topic
`weblate.....`.
When configured, `topic_prefix` is prepended to this topic using a single dot
separator, for example `org.fedoraproject.weblate.project_backed_up.website`.
The action is lowercase textual representation of action with underscores
instead of space, for example `resource_updated`; see [Selected change events](#change-actions)
for all action identifiers. The remaining parts match Weblate object path
segments.
For example, a project backup event for the `website` project uses
`weblate.project_backed_up.website`. A translation change in the `website`
project, `frontend` component, and Czech translation uses
`weblate.translation_changed.website.frontend.cs`. The same change in the
`frontend` component inside the `parent` and `child` categories uses
`weblate.translation_changed.website.parent.child.frontend.cs`.
#### Message body
The body consists of following fields (given that they are available for the event):
`change_id`
: Numerical ID of change
`action`
: Verbose name of the change.
`timestamp`
: ISO formatted timestamp
`target`
: New value of the change (eg. new translation of the string)
`old`
: Old value of the change (eg. previous translation of the string)
`source`
: Source string.
`url`
: Absolute URL to view the related object.
`author`
: Author username (this can be different from user for example when accepting suggestions)
`user`
: Acting username
`project`
: Project slug
`component`
: Component slug
`translation`
: Translation language code
#### Message headers
There are additional headers which you might utilize for routing as well:
`action`
: Verbose name of the change.
`project`
: Project slug
`component`
: Component slug
#### Example messages
Repository merge event:
```json
{
"id": 1,
"action": "Merged repository",
"timestamp": "2017-06-15T11:30:47.325000+00:00",
"url": "http://example.com/projects/test/test/",
"component": "test"
}
```
New source string event:
```json
{
"id": 2,
"action": "New source string",
"timestamp": "2017-06-15T11:30:47.372000+00:00",
"url": "http://example.com/translate/test/test/cs/?checksum=6412684aaf018e8e",
"component": "test",
"translation": "cs",
"source": ["Hello, world!\n"]
}
```
Resource update event:
```json
{
"id": 6,
"action": "Resource update",
"timestamp": "2017-06-15T11:30:47.410000+00:00",
"url": "http://example.com/projects/test/test/cs/",
"project": "test",
"component": "test",
"translation": "cs"
}
{
"id": 7,
"action": "Resource update",
"timestamp": "2017-06-15T11:30:47.510000+00:00",
"url": "http://example.com/projects/test/test/de/",
"project": "test",
"component": "test",
"translation": "de"
}
{
"id": 8,
"action": "Resource update",
"timestamp": "2017-06-15T11:30:47.595000+00:00",
"url": "http://example.com/projects/test/test/it/",
"project": "test",
"component": "test",
"translation": "it"
}
```
Project removal event:
```json
{
"id": 9,
"action": "Removed project",
"timestamp": "2019-10-17T15:57:08.559420+00:00",
"target": "test",
"user": "testuser"
}
```
New contributor event:
```json
{
"id": 11,
"action": "New contributor",
"timestamp": "2019-10-17T15:57:08.759960+00:00",
"url": "http://example.com/translate/test/test/cs/?checksum=6412684aaf018e8e",
"author": "testuser",
"user": "testuser",
"project": "test",
"component": "test",
"translation": "cs",
"source": ["Hello, world!\n"]
}
```
New translation event:
```json
{
"id": 12,
"action": "New translation",
"timestamp": "2019-10-17T15:57:08.772591+00:00",
"url": "http://example.com/translate/test/test/cs/?checksum=6412684aaf018e8e",
"target": ["Ahoj svete!\n"],
"author": "testuser",
"user": "testuser",
"project": "test",
"component": "test",
"translation": "cs",
"source": ["Hello, world!\n"]
}
```
#### SEE ALSO
* [Configuring Fedora Messaging](https://fedora-messaging.readthedocs.io/en/stable/user-guide/configuration.html)
* [Weblate Messaging](https://docs.weblate.org/en/weblate-2026.10/contributing/schemas.md#schema-messaging)
### Bulk edit
* **Add-on ID:**
`weblate.flags.bulk`
* **Configuration:**
| `q` | Query | |
|----------------------------|-----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `state` | State to set | #### Available choices:
| `-1` | Do not change |
|--------|---------------------------------|
| `10` | Needs editing |
| `11` | Needs editing (Needs rewriting) |
| `12` | Needs editing (Needs checking) |
| `20` | Translated |
| `30` | Approved | |
| `add_flags` | Source flags to add — all languages | |
| `remove_flags` | Source flags to remove — all languages | |
| `add_translation_flags` | Translation flags to add — matching translations | Applies only to matching translations, excluding source strings. |
| `remove_translation_flags` | Translation flags to remove — matching translations | Removes locally set flags. Inherited flags remain in effect. |
| `add_labels` | Labels to add — all languages | |
| `remove_labels` | Labels to remove — all languages | |
* **Triggers:**
[Add-on installation](#addon-event-add-on-installation), [Component update](#addon-event-component-update)
Bulk edit flags, labels, or states of strings.
**Examples:**
#### Label new strings automatically
| Search query | `NOT has:label` |
|----------------|-------------------|
| Labels to add | *recent* |
#### Marking all [App store metadata files](https://docs.weblate.org/en/weblate-2026.10/formats/appstore.md#appstore) changelog strings read-only
| Search query | `language:en AND key:changelogs/` |
|--------------------------|-------------------------------------|
| Translation flags to add | `read-only` |
#### Marking certain strings read-only
| Search query | `source:r"^\`\`[.a-zA-Z0-9_-]*\`\`$" AND language:en` |
|--------------------------|---------------------------------------------------------|
| Translation flags to add | `read-only` |
#### SEE ALSO
* [Bulk edit](https://docs.weblate.org/en/weblate-2026.10/user/translating.md#bulk-edit)
* [Customizing behavior using flags](https://docs.weblate.org/en/weblate-2026.10/admin/checks.md#custom-checks)
* [String labels](https://docs.weblate.org/en/weblate-2026.10/devel/translations.md#labels)
### Flag unchanged translations as “Needs rewriting”
* **Add-on ID:**
`weblate.flags.same_edit`
* **Configuration:**
This add-on has no configuration.
* **Triggers:**
[Unit pre-create](#addon-event-unit-pre-create)
Whenever a new translatable string is imported from the VCS and it matches a
source string, it is flagged as needing rewriting in Weblate. Especially useful
for file formats that include source strings for untranslated strings.
#### HINT
You might also want to tighthen the [Unchanged translation](https://docs.weblate.org/en/weblate-2026.10/user/checks.md#check-same) check by adding
`strict-same` flag to [Translation flags](https://docs.weblate.org/en/weblate-2026.10/admin/projects.md#component-check-flags).
#### SEE ALSO
[Translation states](https://docs.weblate.org/en/weblate-2026.10/workflows.md#states)
### Flag new source strings as “Needs checking”
* **Add-on ID:**
`weblate.flags.source_edit`
* **Configuration:**
This add-on has no configuration.
* **Triggers:**
[Unit pre-create](#addon-event-unit-pre-create)
Whenever a new source string is imported from the VCS, it is flagged as needing
checking in Weblate. This way you can easily filter and edit source strings
written by the developers.
#### SEE ALSO
[Translation states](https://docs.weblate.org/en/weblate-2026.10/workflows.md#states)
### Flag new translations as “Needs rewriting”
* **Add-on ID:**
`weblate.flags.target_edit`
* **Configuration:**
This add-on has no configuration.
* **Triggers:**
[Unit pre-create](#addon-event-unit-pre-create)
Whenever a new translatable string is imported from the VCS, it is flagged as
needing rewriting in Weblate. This way you can easily filter and edit
translations created by the developers.
#### SEE ALSO
[Translation states](https://docs.weblate.org/en/weblate-2026.10/workflows.md#states)
### Flag updated translations from repository as “Needs rewriting”
* **Add-on ID:**
`weblate.flags.target_repo_update`
* **Configuration:**
This add-on has no configuration.
* **Triggers:**
[Unit post-sync](#addon-event-unit-post-sync)
Whenever a string translation is changed from the VCS, it is flagged as needing
rewriting in Weblate. Especially useful if translation files are often updated
manually or by an external service.
#### SEE ALSO
[Translation states](https://docs.weblate.org/en/weblate-2026.10/workflows.md#states)
### Fill read-only strings with source
#### Versionadded
Added in version 4.18.
* **Add-on ID:**
`weblate.generate.fill_read_only`
* **Configuration:**
This add-on has no configuration.
* **Triggers:**
[Add-on installation](#addon-event-add-on-installation), [Component update](#addon-event-component-update), [Daily](#addon-event-daily)
Fills in translation of read-only strings with source string.
### Statistics generator
* **Add-on ID:**
`weblate.generate.generate`
* **Configuration:**
| `scope` | Output scope | #### Available choices:
| `translation` | One file per translation |
|-----------------|----------------------------|
| `component` | One file per component | |
|------------|---------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `filename` | Name of generated file | |
| `template` | Content of generated file | |
* **Triggers:**
[Add-on installation](#addon-event-add-on-installation), [Component update](#addon-event-component-update), [Repository post-add](#addon-event-repository-post-add), [Repository post-remove](#addon-event-repository-post-remove), [Repository pre-commit](#addon-event-repository-pre-commit)
Generates a file containing detailed info about the translation status.
You can use a Django template in both filename and content, see [Template markup](https://docs.weblate.org/en/weblate-2026.10/admin/projects.md#markup)
for a detailed markup description.
For example generating a summary file for each translation:
Name of generated file
: `locale/{{ language_code }}.json`
Content
: ```json
{
"language": "{{ language_code }}",
"strings": "{{ stats.all }}",
"translated": "{{ stats.translated }}",
"last_changed": "{{ stats.last_changed }}",
"last_author": "{{ stats.last_author }}",
}
```
#### Component-wide output
Set Output scope to One file per component to maintain
one locale list or statistics file for the entire component. The default,
One file per translation, preserves existing configurations.
Component output is generated on installation and configuration changes. It is
updated when translations are committed, languages are added or removed, and
component files are reloaded. Language metadata changes are included on the
next such update or when the add-on is reconfigured. Unchanged output does not
create a new commit.
Both modes support component and project variables in filenames and content.
In component mode, the content additionally receives `translations`, ordered
by repository language code. Each item provides:
* `language_code`: the language code used in the repository.
* `language_name`: the English language name.
* `language_native_name`: the name translated into its own language using
Weblate’s catalogs, with an English fallback when unavailable.
* `language_direction`: `ltr` or `rtl`.
* `filename` and `url`: the translation filename and Weblate URL.
* `is_source`: whether this is the component’s source translation.
* `stats`: the same statistics available in translation mode.
The source translation is included. Templates can exclude it using
`{% if not item.is_source %}`. Statistics use Weblate’s completion semantics.
Custom language names are retained; there is no external locale-data lookup.
For example, generate `locales.json` for a website:
```django
[
{% for item in translations %}
{
"code": {{ item.language_code|json }},
"file": {{ item.filename|json }},
"name": {{ item.language_native_name|json }},
"dir": {{ item.language_direction|json }}
}{% if not forloop.last %},{% endif %}
{% endfor %}
]
```
Or generate `languages.py` for an application:
```django
names = {
{% for item in translations %}
{{ item.language_code|python }}: {{ item.language_native_name|python }},
{% endfor %}
}
completeness = {
{% for item in translations %}
{{ item.language_code|python }}: {{ item.stats.translated_percent|python }},
{% endfor %}
}
```
The `json` and `python` filters serialize complete values, including string
quotes and escaping. Do not add quotes around their output. They also support
lists and dictionaries; `{{ translations|json }}` exports all available data.
Dates and times are serialized as ISO-formatted strings.
#### SEE ALSO
[Template markup](https://docs.weblate.org/en/weblate-2026.10/admin/projects.md#markup)
### Prefill translation with source
#### Versionadded
Added in version 4.11.
* **Add-on ID:**
`weblate.generate.prefill`
* **Configuration:**
This add-on has no configuration.
* **Triggers:**
[Add-on installation](#addon-event-add-on-installation), [Component update](#addon-event-component-update), [Daily](#addon-event-daily)
Fills in translation strings with source string.
All untranslated strings in the component will be filled with the source
string, and marked as needing edit. Use this when you can not have empty
strings in the translation files.
.. AUTOGENERATED START: weblate.generate.pseudolocale
.. This section is automatically generated by ./manage.py list_addons. Do not edit manually.
### Pseudolocale generation
#### Versionadded
Added in version 4.5.
* **Add-on ID:**
`weblate.generate.pseudolocale`
* **Configuration:**
| `source` | Source strings | |
|--------------------|---------------------------|------------------------------------------------------------------------------------------|
| `target` | Target translation | All strings in this translation will be overwritten |
| `prefix` | Prepended static text | |
| `var_prefix` | Prepended variable text | |
| `suffix` | Appended static text | |
| `var_suffix` | Appended variable text | |
| `var_multiplier` | Variable text multiplier | How many times to repeat the variable text depending on the length of the source string. |
| `include_readonly` | Include read-only strings | |
* **Triggers:**
[Add-on installation](#addon-event-add-on-installation), [Component update](#addon-event-component-update), [Daily](#addon-event-daily)
Generates a translation by adding prefix and suffix to source strings
automatically.
Pseudolocales are useful to find strings that are not prepared for
localization. This is done by altering all translatable source strings
to make it easy to spot unaltered strings when running the application
in the pseudolocale language.
Finding strings whose localized counterparts might not fit the layout
is also possible.
Using the variable parts makes it possible to look for strings which might not
fit into the user interface after the localization - it extends the text based
on the source string length. The variable texts are repeated by length of the
text multiplied by the multiplier. For example `Hello world` with variable
text `_` and variable multiplier of 1 becomes `Hello world___________` -
the text is repeated once for each character in the source string.
The strings will be generated using following pattern:
Prepended static text
Prepended variable text
Source string
Appended variable text
Appended static text
#### HINT
You can use real languages for testing, but there are dedicated
pseudolocales available in Weblate - en_XA and ar_XB.
#### HINT
You can use this add-on to start translation to a new locale of an
existing language or similar language.
Once you add the translation to the component, follow to the add-on.
*Example:* If you have fr and want to start fr_CA translation, simply set
fr as the source, fr_CA as the target, and leave the prefix and suffix blank.
Uninstall the add-on once you have the new translation filled to prevent Weblate
from changing the translations made after the copying.
### Update ALL_LINGUAS variable in the “configure” file
* **Add-on ID:**
`weblate.gettext.configure`
* **Configuration:**
This add-on has no configuration.
* **Triggers:**
[Add-on installation](#addon-event-add-on-installation), [Daily](#addon-event-daily), [Repository post-add](#addon-event-repository-post-add), [Repository post-remove](#addon-event-repository-post-remove)
Updates the ALL_LINGUAS variable in “configure”, “configure.in” or
“configure.ac” files, when a translation is added or removed.
Updates the ALL_LINGUAS variable in `configure`, `configure.in` or any
`configure.ac` files, when a translation is added or removed.
### Customize gettext output
#### Versionremoved
Removed in version 5.13: Replaced by [File format parameters](https://docs.weblate.org/en/weblate-2026.10/formats.md#file-format-params).
### Update gettext template (Django)
#### Versionadded
Added in version 5.17.
* **Add-on ID:**
`weblate.gettext.django`
* **Configuration:**
| `interval` | Update frequency | How often the add-on should update the POT file when the component is refreshed.
#### Available choices:
| `daily` | Daily |
|-----------|---------|
| `weekly` | Weekly |
| `monthly` | Monthly | |
|--------------------|----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `normalize_header` | Normalize POT header | Updates gettext headers and replaces placeholder POT comments. |
| `location_mode` | Source locations | Choose how extraction writes source locations to the POT file. Use this to keep locations in the template while omitting them from translated PO files.
#### Available choices:
| `file` | Use file format settings |
|----------|-----------------------------------|
| `keep` | Extract locations to the POT file |
| `omit` | Do not extract locations | |
* **Triggers:**
[Add-on installation](#addon-event-add-on-installation), [Manual trigger](#addon-event-manual-trigger), [Repository post-update](#addon-event-repository-post-update)
Updates the gettext template using Django’s built-in makemessages command.
This add-on updates the template configured in [Template for new translations](https://docs.weblate.org/en/weblate-2026.10/admin/projects.md#component-new-base).
It is available for gettext PO components, and the component must define a
template for new translations.
The selected update frequency applies to automatic runs after repository
refreshes. Installing or reconfiguring the add-on runs it immediately, and
manual runs from add-on management or the API also bypass the frequency
schedule. After a successful update, Weblate commits the changed template and
reloads source strings.
The template update does not update translation PO files by itself. Keep
[Update PO files to match POT (msgmerge)](#addon-weblate-gettext-msgmerge) installed when translation files should
follow template changes automatically. The install form for this add-on can
install that add-on, but existing add-on settings do not show that installation
option again.
#### Django requirements
This add-on requires **xgettext** and **msguniq**. It runs
Weblate’s internal extraction wrapper for Django messages instead of invoking a
project’s **manage.py makemessages**, so it does not load project Django
settings or applications.
The template for new translations must use the `django` or `djangojs`
domain. Supported template names are `django.pot`, `djangojs.pot`,
`django.po`, and `djangojs.po`. Weblate infers the source directory
from the template path and skips repository locale directories while extracting.
### Update LINGUAS file
* **Add-on ID:**
`weblate.gettext.linguas`
* **Configuration:**
This add-on has no configuration.
* **Triggers:**
[Add-on installation](#addon-event-add-on-installation), [Daily](#addon-event-daily), [Repository post-add](#addon-event-repository-post-add), [Repository post-remove](#addon-event-repository-post-remove)
Updates the LINGUAS file when a translation is added or removed.
### Update POT file (Meson)
#### Versionadded
Added in version 5.17.
* **Add-on ID:**
`weblate.gettext.meson`
* **Configuration:**
| `interval` | Update frequency | How often the add-on should update the POT file when the component is refreshed.
#### Available choices:
| `daily` | Daily |
|-----------|---------|
| `weekly` | Weekly |
| `monthly` | Monthly | |
|---------------------|--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `normalize_header` | Normalize POT header | Updates gettext headers and replaces placeholder POT comments. |
| `location_mode` | Source locations | Choose how extraction writes source locations to the POT file. Use this to keep locations in the template while omitting them from translated PO files.
#### Available choices:
| `file` | Use file format settings |
|----------|-----------------------------------|
| `keep` | Extract locations to the POT file |
| `omit` | Do not extract locations | |
| `data_dirs` | ITS data directories | Newline-separated repository-relative directories containing an its subdirectory, for example po for po/its. Earlier directories override later directories and bundled rules. |
| `comment_mode` | Code comments | Choose whether xgettext should extract no comments, all comments, or only comments marked with a specific tag.
#### Available choices:
| `off` | Do not extract comments |
|----------|---------------------------|
| `all` | Extract all comments |
| `tagged` | Extract comments with tag | |
| `comment_tag` | Comment tag | Tag passed to xgettext for comment extraction when using tagged comment mode. |
| `checks` | xgettext checks | Additional xgettext validation checks to enable for extracted messages.
#### Available choices:
| `ellipsis-unicode` | ellipsis-unicode |
|----------------------|--------------------|
| `space-ellipsis` | space-ellipsis |
| `quote-unicode` | quote-unicode |
| `bullet-unicode` | bullet-unicode | |
| `keyword` | Additional keywords | Newline-separated extra keywords passed to xgettext using –keyword. |
| `keyword_exclusive` | Use keywords exclusively | When enabled, passes `--keyword` without a value to xgettext before the additional keyword, disabling all default keywords so that only the keyword specified above is recognized. |
| `preset` | Meson preset | Built-in xgettext argument preset matching Meson gettext integration. The GLib preset adds the keyword and format-flag options used by Meson’s gettext helper.
#### Available choices:
| `glib` | GLib |
|----------|--------| |
* **Triggers:**
[Add-on installation](#addon-event-add-on-installation), [Manual trigger](#addon-event-manual-trigger), [Repository post-update](#addon-event-repository-post-update)
Updates the gettext template using Meson gettext conventions.
This add-on updates the template configured in [Template for new translations](https://docs.weblate.org/en/weblate-2026.10/admin/projects.md#component-new-base).
It is available for gettext PO components, and the component must define a
template for new translations.
The selected update frequency applies to automatic runs after repository
refreshes. Installing or reconfiguring the add-on runs it immediately, and
manual runs from add-on management or the API also bypass the frequency
schedule. After a successful update, Weblate commits the changed template and
reloads source strings.
The template update does not update translation PO files by itself. Keep
[Update PO files to match POT (msgmerge)](#addon-weblate-gettext-msgmerge) installed when translation files should
follow template changes automatically. The install form for this add-on can
install that add-on, but existing add-on settings do not show that installation
option again.
#### Meson requirements
This add-on requires **xgettext**; it does not invoke Meson. It follows
Meson gettext conventions by reading `POTFILES` or `POTFILES.in`
from the gettext directory and passing the GLib keyword and format-flag preset
to **xgettext**.
The gettext directory is the directory containing the template configured in
[Template for new translations](https://docs.weblate.org/en/weblate-2026.10/admin/projects.md#component-new-base). It must contain `meson.build` and
`POTFILES` or `POTFILES.in`. A Meson project `meson.build`
must be present in that directory or one of its parent directories. If both
`POTFILES` and `POTFILES.in` exist, `POTFILES` is used.
An adjacent `POTFILES.skip` excludes listed source files from extraction.
Configure this add-on from the existing Meson gettext setup. In most Meson
projects, the gettext directory is `po/`, the template is named after the
gettext domain, and `po/meson.build` calls Meson’s gettext helper. Use the
same template path in [Template for new translations](https://docs.weblate.org/en/weblate-2026.10/admin/projects.md#component-new-base), for example
`po/example.pot`, and keep `POTFILES` or `POTFILES.in` next to
that `meson.build` file.
Weblate does not read the source file list from `meson.build`. It uses
`POTFILES` or `POTFILES.in`, matching Meson’s gettext convention.
When the Meson project uses a non-default gettext directory or domain, mirror
that layout in the component template path.
### Generate MO files
* **Add-on ID:**
`weblate.gettext.mo`
* **Configuration:**
| `path` | Path of generated MO file | If not specified, the location of the PO file will be used. |
|----------|---------------------------------|----------------------------------------------------------------------------------|
| `fuzzy` | Include strings needing editing | Strings needing editing (fuzzy) are typically not ready for use as translations. |
* **Triggers:**
[Repository pre-commit](#addon-event-repository-pre-commit)
Automatically generates a MO file for every changed PO file.
The location of the generated MO file can be customized and the field for it uses [Template markup](https://docs.weblate.org/en/weblate-2026.10/admin/projects.md#markup).
#### NOTE
If a translation is removed, its PO file will be deleted from the
repository, but the MO file generated by this add-on will not. The MO file
must be removed from the upstream manually.
### Update PO files to match POT (msgmerge)
#### Versionchanged
Changed in version 5.13: Settings configuration has been moved to [File format parameters](https://docs.weblate.org/en/weblate-2026.10/formats.md#file-format-params).
* **Add-on ID:**
`weblate.gettext.msgmerge`
* **Configuration:**
This add-on has no configuration.
* **Triggers:**
[Add-on installation](#addon-event-add-on-installation), [Repository post-update](#addon-event-repository-post-update)
Updates all PO files (as configured by “File mask”) to match the POT file (as
configured by “Template for new translations”) using msgmerge.
This add-on is essential when working with gettext PO files where the POT
(template) file is updated with new strings or changes to existing strings.
When the POT file is updated in the repository, this add-on automatically
merges those changes into all language PO files, ensuring that:
* New translatable strings appear in all languages
* Removed strings are marked as obsolete
* Modified strings are marked as needing review (fuzzy)
Most msgmerge command-line options can be set up through file format parameters
configuration. Enable the `po_remove_obsolete` parameter to remove obsolete
`#~` entries when PO files are saved.
#### SEE ALSO
* [File mask](https://docs.weblate.org/en/weblate-2026.10/admin/projects.md#component-filemask)
* [Template for new translations](https://docs.weblate.org/en/weblate-2026.10/admin/projects.md#component-new-base)
* **msgmerge**
* [Does Weblate update translation files besides translations?](https://docs.weblate.org/en/weblate-2026.10/faq.md#faq-cleanup)
* [Updating target-language files](https://docs.weblate.org/en/weblate-2026.10/devel/integration.md#updating-target-files)
### Update POT file (Sphinx)
#### Versionadded
Added in version 5.17.
* **Add-on ID:**
`weblate.gettext.sphinx`
* **Configuration:**
| `interval` | Update frequency | How often the add-on should update the POT file when the component is refreshed.
#### Available choices:
| `daily` | Daily |
|-----------|---------|
| `weekly` | Weekly |
| `monthly` | Monthly | |
|--------------------|----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `normalize_header` | Normalize POT header | Updates gettext headers and replaces placeholder POT comments. |
| `location_mode` | Source locations | Choose how extraction writes source locations to the POT file. Use this to keep locations in the template while omitting them from translated PO files.
#### Available choices:
| `file` | Use file format settings |
|----------|-----------------------------------|
| `keep` | Extract locations to the POT file |
| `omit` | Do not extract locations | |
| `filter_mode` | Filtering | Optionally remove strings that are not useful to translate after Sphinx extraction.
#### Available choices:
| `none` | None |
|----------------|-----------------------|
| `weblate_docs` | Weblate documentation | |
* **Triggers:**
[Add-on installation](#addon-event-add-on-installation), [Manual trigger](#addon-event-manual-trigger), [Repository post-update](#addon-event-repository-post-update)
Updates the gettext template using Sphinx’s gettext builder without loading
project configuration.
This add-on updates the template configured in [Template for new translations](https://docs.weblate.org/en/weblate-2026.10/admin/projects.md#component-new-base).
It is available for gettext PO components, and the component must define a
template for new translations.
The selected update frequency applies to automatic runs after repository
refreshes. Installing or reconfiguring the add-on runs it immediately, and
manual runs from add-on management or the API also bypass the frequency
schedule. After a successful update, Weblate commits the changed template and
reloads source strings.
The template update does not update translation PO files by itself. Keep
[Update PO files to match POT (msgmerge)](#addon-weblate-gettext-msgmerge) installed when translation files should
follow template changes automatically. The install form for this add-on can
install that add-on, but existing add-on settings do not show that installation
option again.
#### Sphinx requirements
This add-on requires **sphinx-build**, provided by the `sphinx`
installation extra. The template for new translations must be a `.pot`
file below a `locales` directory. The directory before `locales` is
used as the Sphinx source directory and must contain `conf.py`.
Extraction uses Weblate’s bundled Sphinx configuration and does not load the
project configuration. Weblate runs the Sphinx gettext builder, normalizes
source references to paths relative to the source directory, and copies the
generated template back to the configured template path.
### Update POT file (xgettext)
#### Versionadded
Added in version 5.17.
* **Add-on ID:**
`weblate.gettext.xgettext`
* **Configuration:**
| `interval` | Update frequency | How often the add-on should update the POT file when the component is refreshed.
#### Available choices:
| `daily` | Daily |
|-----------|---------|
| `weekly` | Weekly |
| `monthly` | Monthly | |
|---------------------|--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `normalize_header` | Normalize POT header | Updates gettext headers and replaces placeholder POT comments. |
| `location_mode` | Source locations | Choose how extraction writes source locations to the POT file. Use this to keep locations in the template while omitting them from translated PO files.
#### Available choices:
| `file` | Use file format settings |
|----------|-----------------------------------|
| `keep` | Extract locations to the POT file |
| `omit` | Do not extract locations | |
| `data_dirs` | ITS data directories | Newline-separated repository-relative directories containing an its subdirectory, for example po for po/its. Earlier directories override later directories and bundled rules. |
| `comment_mode` | Code comments | Choose whether xgettext should extract no comments, all comments, or only comments marked with a specific tag.
#### Available choices:
| `off` | Do not extract comments |
|----------|---------------------------|
| `all` | Extract all comments |
| `tagged` | Extract comments with tag | |
| `comment_tag` | Comment tag | Tag passed to xgettext for comment extraction when using tagged comment mode. |
| `checks` | xgettext checks | Additional xgettext validation checks to enable for extracted messages.
#### Available choices:
| `ellipsis-unicode` | ellipsis-unicode |
|----------------------|--------------------|
| `space-ellipsis` | space-ellipsis |
| `quote-unicode` | quote-unicode |
| `bullet-unicode` | bullet-unicode | |
| `keyword` | Additional keywords | Newline-separated extra keywords passed to xgettext using –keyword. |
| `keyword_exclusive` | Use keywords exclusively | When enabled, passes `--keyword` without a value to xgettext before the additional keyword, disabling all default keywords so that only the keyword specified above is recognized. |
| `input_mode` | Input source | Choose whether xgettext should read source files from glob patterns or from a POTFILES/POTFILES.in manifest.
#### Available choices:
| `patterns` | Source file patterns |
|--------------|------------------------|
| `potfiles` | POTFILES manifest | |
| `language` | xgettext language | Programming language passed to xgettext, for example Python or C. Leave blank to let xgettext guess the language from file extensions. |
| `source_patterns` | Source file patterns | Newline-separated repository-relative glob patterns for files to extract with xgettext. |
| `potfiles_path` | POTFILES path | Repository-relative path to POTFILES or POTFILES.in. Entries are resolved relative to the repository root. If present next to the manifest, POTFILES.skip excludes listed files from extraction. |
* **Triggers:**
[Add-on installation](#addon-event-add-on-installation), [Manual trigger](#addon-event-manual-trigger), [Repository post-update](#addon-event-repository-post-update)
Updates the gettext template using xgettext on selected source files.
This add-on updates the template configured in [Template for new translations](https://docs.weblate.org/en/weblate-2026.10/admin/projects.md#component-new-base).
It is available for gettext PO components, and the component must define a
template for new translations.
The selected update frequency applies to automatic runs after repository
refreshes. Installing or reconfiguring the add-on runs it immediately, and
manual runs from add-on management or the API also bypass the frequency
schedule. After a successful update, Weblate commits the changed template and
reloads source strings.
The template update does not update translation PO files by itself. Keep
[Update PO files to match POT (msgmerge)](#addon-weblate-gettext-msgmerge) installed when translation files should
follow template changes automatically. The install form for this add-on can
install that add-on, but existing add-on settings do not show that installation
option again.
#### xgettext requirements
This add-on requires **xgettext**. Configure either source file patterns
or a `POTFILES` / `POTFILES.in` manifest. Source file patterns are
repository-relative glob patterns and only matching repository files are passed
to **xgettext**.
Entries in `POTFILES` or `POTFILES.in` are resolved relative to the
repository root. They must be relative paths, stay inside the repository, and
point to existing files. Blank lines and lines starting with `#` are ignored.
If a `POTFILES.skip` file exists next to the manifest, its entries are
excluded from extraction.
Automatic repository refresh runs are skipped unless the changed files match
the configured source patterns, match files listed in the manifest, change a
watched manifest, or change the add-on configuration.
Start from the build-system extraction setup when configuring this add-on.
Autotools projects usually keep gettext inputs in `po/POTFILES.in` and
options such as the gettext domain and **xgettext** flags in
`po/Makevars` or related `Makefile.am` files. Use manifest mode
with the same `POTFILES.in` when its entries are plain repository-relative
source paths, and copy relevant extraction behavior into the add-on settings,
for example the language, comment extraction, checks, and additional keyword.
For other build systems, use the source list or extraction command they already
run as the source of truth. CMake, custom Makefiles, npm scripts, or project
specific extraction scripts often call **xgettext** directly or generate
an intermediate file list. Configure source patterns for simple layouts, or use
manifest mode when the project maintains a plain file list. If a build-system
manifest contains transformations or prefixes that are not file paths, convert
it to plain repository-relative paths before using it as `POTFILES`.
#### Mixed source formats and ITS rules
Leave xgettext language blank to extract messages from different
formats into the same POT. Include all inputs in the source patterns or
`POTFILES`, for example:
```text
common/messages.py
qt/application.desktop
qt/application.policy
data/application.metainfo.xml
```
Desktop entries use the native **xgettext** parser. Weblate bundles ITS
rules for Polkit policies, AppStream/MetaInfo, GSettings, GTK Builder, and Shared
MIME Info. These rules are included in the Weblate package, including Docker
installations; no additional system packages are required for these formats.
The [Update POT file (Meson)](#addon-weblate-gettext-meson) add-on uses the same rules.
Extraction follows upstream gettext and ITS behavior. In particular, desktop
extraction includes keys such as `Name`, `GenericName`, and `Comment`;
Polkit rules select `description` and `message` elements without filtering
by `gettext-domain`. Use untranslated policy sources: upstream Polkit rules
also select elements carrying `xml:lang`.
For custom XML formats or overrides, configure ITS data directories.
Enter one repository-relative directory per line, in priority order. Each must
contain an `its/` subdirectory with `.loc` locating rules and `.its`
extraction rules. For example, enter `po` for `po/its/example.loc` and
`po/its/example.its`, or `.` for `its/` at the repository root.
In API add-on configuration, use a list: `"data_dirs": ["po", "data"]`.
Earlier directories take precedence over later ones, followed by Weblate’s
bundled rules and gettext’s system rules. The directories are passed through
`GETTEXTDATADIRS`. Configure them explicitly even when using Meson; Weblate
does not read `data_dirs` from `meson.build` or inherit an administrator’s
`GETTEXTDATADIRS` environment variable.
Rule directories and files must stay inside the repository and must not be
symbolic links. A locating rule’s `target` must name an existing `.its` file
in the same directory. DTDs, entity declarations, and external rule references
are not supported. Weblate validates project-local rules before extraction and
reports invalid rules as add-on errors. Changes, additions, or deletions in the
configured `its/` directories trigger extraction even when source files
have not changed.
#### SEE ALSO
[GNU gettext ITS rules](https://www.gnu.org/software/gettext/manual/html_node/ITS-Rules.html)
and [locating rules](https://www.gnu.org/software/gettext/manual/html_node/Locating-Rules.html).
### Squash Git commits
* **Add-on ID:**
`weblate.git.squash`
* **Configuration:**
| `squash` | Commit squashing | #### Available choices:
| `all` | All commits into one |
|-------------------|-------------------------|
| `language` | Per language |
| `file` | Per file |
| `author` | Per author |
| `author-language` | Per author and language | |
|-------------------|--------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `append_trailers` | Append trailers to squashed commit message | Trailer lines are lines that look similar to RFC 822 e-mail headers, at the end of the otherwise free-form part of a commit message, such as ‘Co-authored-by: …’. |
| `commit_message` | Commit message | This commit message will be used instead of the combined commit messages from the squashed commits. |
* **Triggers:**
[Add-on installation](#addon-event-add-on-installation), [Repository post-commit](#addon-event-repository-post-commit)
Squash Git commits prior to pushing changes.
#### HINT
To avoid unnecessary conflicts, it is recommended to configure automatic
receiving of upstream changes by webhooks or API, see [Updating repositories](https://docs.weblate.org/en/weblate-2026.10/admin/continuous.md#update-vcs).
Git commits can be squashed prior to pushing changes
in one of the following modes:
* All commits into one
* Per language
* Per file
* Per author
* Per author and language
Original commit messages are kept, but authorship is lost unless Per author is selected, or
the commit message is customized to include it.
The original commit messages can optionally be overridden with a custom commit message.
Trailers (commit lines like `Co-authored-by: …`) can optionally be removed
from the original commit messages and appended to the end of the squashed
commit message. This also generates proper `Co-authored-by:` credit for every
translator.
### Customize JSON output
#### Versionchanged
Changed in version 5.12: Avoid spaces after separators option added.
#### Versionremoved
Removed in version 5.13: Replaced by [File format parameters](https://docs.weblate.org/en/weblate-2026.10/formats.md#file-format-params).
### Reset repository to upstream
#### Versionadded
Added in version 5.17.
* **Add-on ID:**
`weblate.hosted.reset`
* **Configuration:**
This add-on has no configuration.
* **Triggers:**
[Add-on installation](#addon-event-add-on-installation), [Daily](#addon-event-daily)
Discards all changes in the Weblate repository each night.
### Format the Java properties file
* **Add-on ID:**
`weblate.properties.sort`
* **Configuration:**
| `case_sensitive` | Enable case-sensitive key sorting | |
|--------------------|-------------------------------------|----|
* **Triggers:**
[Repository pre-commit](#addon-event-repository-pre-commit)
Formats and sorts the Java properties file.
* Consolidates newlines to Unix ones.
* Uppercase formatting of Unicode escape sequences (in case they are present).
* Strips blank lines and comments.
* Sorts the strings by the keys.
* Drops duplicate strings.
### Stale comment removal
* **Add-on ID:**
`weblate.removal.comments`
* **Configuration:**
| `age` | Days to keep | |
|---------|----------------|----|
* **Triggers:**
[Add-on installation](#addon-event-add-on-installation), [Daily](#addon-event-daily)
Set a timeframe for removal of comments.
This can be useful to remove old
comments which might have become outdated. Use with care as comments
getting old does not mean they have lost their importance.
### Stale suggestion removal
* **Add-on ID:**
`weblate.removal.suggestions`
* **Configuration:**
| `age` | Days to keep | |
|---------|------------------|--------------------------------------------------------------------------------------------------------------------------------|
| `votes` | Voting threshold | Threshold for removal. Leave empty to remove suggestions regardless of votes. This field has no effect with voting turned off. |
* **Triggers:**
[Add-on installation](#addon-event-add-on-installation), [Daily](#addon-event-daily)
Set a timeframe for removal of suggestions.
Can be very useful in connection with suggestion voting
(see [Peer review](https://docs.weblate.org/en/weblate-2026.10/workflows.md#peer-review)) to remove suggestions which
don’t receive enough positive votes in a given timeframe.
### Update RESX files
* **Add-on ID:**
`weblate.resx.update`
* **Configuration:**
This add-on has no configuration.
* **Triggers:**
[Add-on installation](#addon-event-add-on-installation), [Repository post-update](#addon-event-repository-post-update)
Update all translation files to match the monolingual upstream base file.
Unused strings are removed, and new ones added as copies of the source string.
#### HINT
Use [Cleanup translation files](#addon-weblate-cleanup-generic) if you only want to remove stale
translation keys.
#### SEE ALSO
[Does Weblate update translation files besides translations?](https://docs.weblate.org/en/weblate-2026.10/faq.md#faq-cleanup)
### Slack Webhooks
#### Versionadded
Added in version 5.12.
* **Add-on ID:**
`weblate.webhook.slack`
* **Configuration:**
| `webhook_url` | Webhook URL | |
|-----------------|--------------------------|------------------------------------------------------------------------------------------------------------------------------------|
| `event_filter` | Change events to trigger | Choose which change events should trigger this add-on.
[Change events to trigger](#addon-choice-event-filter) |
| `events` | Selected change events | [Selected change events](#addon-choice-events) |
* **Triggers:**
[Event change](#addon-event-event-change)
Sends notification to a Slack channel based on selected events.
#### WARNING
The notification content might show HTML tags. This is a known issue that will be soon addressed; see [https://github.com/WeblateOrg/weblate/issues/15056](https://github.com/WeblateOrg/weblate/issues/15056).
#### HINT
To obtain a webhook URL, follow the steps outlined in the [Slack Incoming Webhooks documentation](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks)
### Webhook
#### Versionadded
Added in version 5.11.
#### Versionchanged
Changed in version 5.15: Compliance of the secret length with the specification is now validated.
* **Add-on ID:**
`weblate.webhook.webhook`
* **Configuration:**
| `webhook_url` | Webhook URL | |
|-----------------|--------------------------|------------------------------------------------------------------------------------------------------------------------------------|
| `secret` | Webhook secret | The Standard Webhooks secret is a base64 encoded string. |
| `event_filter` | Change events to trigger | Choose which change events should trigger this add-on.
[Change events to trigger](#addon-choice-event-filter) |
| `events` | Selected change events | [Selected change events](#addon-choice-events) |
* **Triggers:**
[Event change](#addon-event-event-change)
Sends notifications to external services based on selected events, following
the Standard Webhooks specification.
The request payload complies with the [Weblate Messaging](https://docs.weblate.org/en/weblate-2026.10/contributing/schemas.md#schema-messaging) schema. The
`action` field uses the action name listed in [Selected change events](#change-actions).
The OpenAPI description can also be found at `/api/docs/`.
Sample request body:
```json
{
"change_id": 99,
"action": "Translation changed",
"timestamp": "2019-08-24T14:15:22Z",
"target": "Nazdar svete!",
"old": "Nazdar!",
"source": "Hello, world",
"url": "/translate/project-slug/component-slug/cs/?checksum=46add148a53cab6f",
"author": "author-username",
"user": "user-username",
"project": "project-slug",
"component": "component-slug",
"translation": "cs"
}
```
Sample request body with categories:
```json
{
"change_id": 8910,
"action": "Component renamed",
"timestamp": "2025-06-11T07:15:09Z",
"target": ["new-name"],
"old": ["component-slug"],
"url": "/projects/project-slug/parent-category/child-category/sub-category/component-slug/",
"user": "testuser",
"project": "project-slug",
"component": "component-slug",
"category": [
"sub-category",
"child-category",
"parent-category"
]
}
```
Sample request headers:
```json
{
"webhook-id": "7f1c5477f6275a69af7b83236c20cb1a",
"webhook-timestamp": "1748505623.044281",
"webhook-signature": "v1,Ceo5qEr07ixe2NLpvHk3FH9bwy/WavXrAFQ/9tdO6mc="
}
```
The `webhook-signature` is a space separated list of HMAC signatures generated using the `secret` string,
the request payload, the `webhook-timestamp`, and the `webhook-id`. This ensures the authenticity
and integrity of the webhook request.
The provided `secret` is a base64 encoded string between 24 bytes (192 bits)
and 64 bytes (512 bits). It can be prefixed with `whsec_` for easy
identification.
To verify a request, you can use the `Webhook.verify` method from the `standardwebhooks` library
or an implementation of the “Standard Webhooks Specification”.
#### SEE ALSO
* [Standard Webhooks Specification](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md)
* [Weblate Messaging](https://docs.weblate.org/en/weblate-2026.10/contributing/schemas.md#schema-messaging)
* [Python library for Standard Webhooks](https://pypi.org/project/standardwebhooks/)
The [Automatic translation](#addon-weblate-autotranslate-autotranslate) mode
Add as approved translation creates approved strings when reviews are
enabled for the target language. If the project settings or a language workflow
override disable reviews, it creates translated strings instead. The configured
mode is preserved, including for project-wide and site-wide add-ons whose targets
have different review settings. Configuring this mode requires the usual add-on
management permission; it does not require the configuring user to be a reviewer.
The [Component discovery](#addon-weblate-discovery-discovery) add-on stops with an error if the
repository scan exceeds 100,000 paths or matching translation files would
require more than 1,000,000 path-to-mask comparisons. The comparison limit is
checked using the number of repository paths multiplied by the number of file
masks. These fixed limits bound resource consumption when repository content
determines the masks. When either limit is exceeded, discovery does not create
or remove components.
## Obsolete add-ons
### Contributors in comment
#### Versionremoved
Removed in version 2026.10: Replaced by [Contributor comments](https://docs.weblate.org/en/weblate-2026.10/formats/gettext.md#gettext-contributor-comments).
Existing installations of `weblate.gettext.authors` are migrated to the
`gettext` value of the `po_contributor_comments` file format parameter for
each affected PO component. This includes components covered by category-,
project-, and site-wide installations. New components default to disabled unless
their file format parameters are copied from another component.
Remove `weblate.addons.gettext.GettextAuthorComments` from custom
[`WEBLATE_ADDONS`](https://docs.weblate.org/en/weblate-2026.10/admin/config.md#std-setting-WEBLATE_ADDONS) lists and `weblate.gettext.authors` entries from
[`DEFAULT_ADDONS`](https://docs.weblate.org/en/weblate-2026.10/admin/config.md#std-setting-DEFAULT_ADDONS). Configure [Contributor comments](https://docs.weblate.org/en/weblate-2026.10/formats/gettext.md#gettext-contributor-comments) instead.
### Customize XML output
#### Versionadded
Added in version 4.15.
#### Versionremoved
Removed in version 5.13: Replaced by [File format parameters](https://docs.weblate.org/en/weblate-2026.10/formats.md#file-format-params).
### Customize YAML output
#### Versionremoved
Removed in version 5.13: Replaced by [File format parameters](https://docs.weblate.org/en/weblate-2026.10/formats.md#file-format-params).
## Common add-on parameters
### Machine translation engines
#### Available choices:
| `alibaba` | Alibaba |
|------------------------------|-----------------------------------|
| `aws` | Amazon Translate |
| `anthropic` | Anthropic |
| `apertium-apy` | Apertium APy |
| `microsoft-translator` | Azure AI Translator |
| `azure-openai` | Azure OpenAI |
| `baidu` | Baidu |
| `cyrtranslit` | CyrTranslit |
| `deepl` | DeepL |
| `glosbe` | Glosbe |
| `google-translate-api-v3` | Google Cloud Translation Advanced |
| `google-translate` | Google Cloud Translation Basic |
| `ltengine` | LTEngine |
| `libretranslate` | LibreTranslate |
| `mistral` | Mistral |
| `modernmt` | ModernMT |
| `mymemory` | MyMemory |
| `netease-sight` | Netease Sight |
| `ollama` | Ollama |
| `openai` | OpenAI |
| `sap-translation-hub` | SAP Translation Hub |
| `systran` | Systran |
| `weblate` | Weblate |
| `weblate-translation-memory` | Weblate Translation Memory |
| `yandex` | Yandex |
| `yandex-v2` | Yandex v2 |
| `youdao-zhiyun` | Youdao Zhiyun |
| `tmserver` | tmserver |
### File format
#### Available choices:
| `apple-xliff` | XLIFF 1.2 with Apple extensions |
|-------------------------|------------------------------------------|
| `appstore` | App store metadata files |
| `arb` | ARB file |
| `aresource` | Android String Resource |
| `asciidoc` | AsciiDoc file |
| `ass` | Advanced SubStation Alpha subtitle file |
| `catkeys` | Haiku catkeys |
| `cmp-resource` | Compose Multiplatform Resource |
| `csv` | CSV file |
| `csv-multi` | Multivalue CSV file |
| `csv-simple` | Simple CSV file |
| `dokuwiki` | DokuWiki text file |
| `dtd` | DTD file |
| `flatxml` | Flat XML file |
| `fluent` | Fluent file |
| `formatjs` | Format.JS JSON file |
| `go-i18n-json` | go-i18n v1 JSON file |
| `go-i18n-json-v2` | go-i18n v2 JSON file |
| `go-i18n-toml` | go-i18n TOML file |
| `gotext` | gotext JSON file |
| `gwt` | GWT properties |
| `html` | HTML file |
| `i18next` | i18next JSON file v3 |
| `i18nextv4` | i18next JSON file v4 |
| `idml` | IDML file |
| `ini` | INI file |
| `islu` | Inno Setup INI file |
| `joomla` | Joomla language file |
| `json` | JSON file |
| `json-nested` | JSON nested structure file |
| `laravel` | Laravel PHP strings |
| `markdown` | Markdown file |
| `mdx` | MDX file |
| `mediawiki` | MediaWiki text file |
| `mi18n-lang` | @draggable/i18n lang file |
| `moko-resource` | Mobile Kotlin Resource |
| `nextcloud-json` | Nextcloud JSON file |
| `odf` | OpenDocument file |
| `php` | PHP strings |
| `po` | gettext PO file |
| `po-mono` | gettext PO file (monolingual) |
| `poxliff` | XLIFF 1.2 with gettext extensions |
| `properties` | Java Properties |
| `rc` | RC file |
| `resjson` | RESJSON file |
| `resourcedictionary` | ResourceDictionary file |
| `resx` | .NET resource file |
| `ruby-yaml` | Ruby YAML file |
| `srt` | SubRip subtitle file |
| `ssa` | SubStation Alpha subtitle file |
| `strings` | iOS strings |
| `stringsdict` | Stringsdict file |
| `sub` | MicroDVD subtitle file |
| `tbx` | TermBase eXchange file |
| `toml` | TOML file |
| `ts` | Qt Linguist translation file (version 2) |
| `ts1` | Qt Linguist translation file (version 1) |
| `txt` | Plain text file |
| `webextension` | WebExtension JSON file |
| `wxl` | WixLocalization file |
| `xliff` | XLIFF 1.2 translation file |
| `xliff2` | XLIFF 2.0 translation file |
| `xlsx` | Excel Open XML |
| `xwiki-fullpage` | XWiki Full Page |
| `xwiki-java-properties` | XWiki Java Properties |
| `xwiki-page-properties` | XWiki Page Properties |
| `yaml` | YAML file |
### Change events to trigger
#### Available choices:
| `content` | Translation content events |
|-------------|------------------------------|
| `all` | All change events |
| `custom` | Selected change events |
### Selected change events
The following change actions can appear in notification payloads. Fedora Messaging uses the identifier column in message topics, while webhook payloads use the name column in the `action` field.
#### Available choices:
| ID | Identifier | Name | Description |
|-------|------------------------------------------|----------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `0` | `resource_updated` | Resource updated | A translation file was synchronized with its repository. |
| `1` | `translation_completed` | Translation completed | A language translation became fully translated after an individual edit. Automatic translation, uploads, and bulk edits do not emit this event. |
| `2` | `translation_changed` | Translation changed | An existing translation was edited by a user. |
| `3` | `comment_added` | Comment added | A comment was added to a string. |
| `4` | `suggestion_added` | Suggestion added | A translation suggestion was added. |
| `5` | `translation_added` | Translation added | A previously untranslated string was translated by a user. |
| `6` | `automatically_translated` | Automatically translated | A translation was added or changed by automatic translation. This is emitted instead of Translation added or Translation changed. |
| `7` | `suggestion_accepted` | Suggestion accepted | A translation suggestion was accepted as the translation. |
| `8` | `translation_reverted` | Translation reverted | A translation was restored to an earlier value. |
| `9` | `translation_uploaded` | Translation uploaded | A translation was added or changed by a translation file upload. This is emitted instead of Translation added or Translation changed. |
| `13` | `source_string_added` | Source string added | A source string was added outside repository or upload updates. |
| `14` | `component_locked` | Component locked | A component was locked for translation. |
| `15` | `component_unlocked` | Component unlocked | A component was unlocked for translation. |
| `17` | `changes_committed` | Changes committed | Pending component changes were committed. |
| `18` | `changes_pushed` | Changes pushed | Repository changes were pushed upstream. |
| `19` | `repository_reset` | Repository reset | A repository was reset to its upstream state. |
| `20` | `repository_merged` | Repository merged | Upstream repository changes were merged. |
| `21` | `repository_rebased` | Repository rebased | Repository changes were rebased on upstream. |
| `22` | `repository_merge_failed` | Repository merge failed | Merging upstream repository changes failed. |
| `23` | `repository_rebase_failed` | Repository rebase failed | Rebasing repository changes failed. |
| `24` | `parsing_failed` | Parsing failed | Weblate could not parse a translation file. |
| `25` | `translation_removed` | Translation removed | A language translation was removed. |
| `26` | `suggestion_removed` | Suggestion removed | A translation suggestion was removed. |
| `27` | `translation_replaced` | Translation replaced | A translation was changed by a search-and-replace operation. This is emitted instead of Translation changed. |
| `28` | `repository_push_failed` | Repository push failed | Pushing repository changes upstream failed. |
| `29` | `suggestion_removed_during_cleanup` | Suggestion removed during cleanup | An obsolete translation suggestion was removed during cleanup. |
| `30` | `source_string_changed` | Source string changed | A source string was edited in Weblate. |
| `31` | `string_added` | String added | A new string was added in Weblate. |
| `32` | `bulk_status_changed` | Bulk status changed | The translation state of one or more strings was changed in bulk. |
| `33` | `visibility_changed` | Visibility changed | Project or component visibility was changed. |
| `34` | `user_added` | User added | A user was granted access. |
| `35` | `user_removed` | User removed | A user’s access was removed. |
| `36` | `translation_approved` | Translation approved | A translation was approved during review. |
| `37` | `marked_for_edit` | Marked for edit | A translation was marked as needing editing. |
| `38` | `component_removed` | Component removed | A translation component was removed. |
| `39` | `project_removed` | Project removed | A translation project was removed. |
| `41` | `project_renamed` | Project renamed | A translation project was renamed. |
| `42` | `component_renamed` | Component renamed | A translation component was renamed. |
| `43` | `moved_component` | Moved component | A component was moved within a project. |
| `45` | `contributor_joined` | Contributor joined | A user made their first contribution to a translation. |
| `46` | `announcement_posted` | Announcement posted | An announcement was posted. |
| `47` | `alert_triggered` | Alert triggered | A component alert was triggered. |
| `48` | `language_added` | Language added | A language translation was added. |
| `49` | `language_requested` | Language requested | A user requested a new language. |
| `50` | `project_created` | Project created | A translation project was created. |
| `51` | `component_created` | Component created | A translation component was created. |
| `52` | `user_invited` | User invited | A user was invited to a project. |
| `53` | `repository_notification_received` | Repository notification received | Weblate received a repository notification from a code host. |
| `54` | `translation_replaced_file_by_upload` | Translation replaced file by upload | A translation file was replaced by an uploaded file. |
| `55` | `license_changed` | License changed | Project or component license information changed. |
| `56` | `contributor_license_agreement_changed` | Contributor license agreement changed | The contributor license agreement was changed. |
| `57` | `screenshot_added` | Screenshot added | A screenshot was associated with a string. |
| `58` | `screenshot_uploaded` | Screenshot uploaded | A screenshot image was uploaded. |
| `59` | `string_updated_in_the_repository` | String updated in the repository | A string was changed while synchronizing from the repository. |
| `60` | `add-on_installed` | Add-on installed | An add-on was installed. |
| `61` | `add-on_configuration_changed` | Add-on configuration changed | An add-on’s configuration was changed. |
| `62` | `add-on_uninstalled` | Add-on uninstalled | An add-on was uninstalled. |
| `63` | `string_removed` | String removed | A string was removed from a translation. |
| `64` | `comment_removed` | Comment removed | A string comment was removed. |
| `65` | `comment_resolved` | Comment resolved | A string comment was marked as resolved. |
| `66` | `explanation_updated` | Explanation updated | The explanation for a source string was updated. |
| `67` | `category_removed` | Category removed | A component category was removed. |
| `68` | `category_renamed` | Category renamed | A component category was renamed. |
| `69` | `category_moved` | Category moved | A component category was moved. |
| `70` | `saving_string_failed` | Saving string failed | Weblate could not save a changed string. |
| `71` | `string_added_in_the_repository` | String added in the repository | A new string was found while synchronizing from the repository. |
| `72` | `string_updated_in_the_upload` | String updated in the upload | A string was changed while processing an uploaded file. |
| `73` | `string_added_in_the_upload` | String added in the upload | A new string was found while processing an uploaded file. |
| `74` | `translation_updated_by_source_upload` | Translation updated by source upload | A translation was synchronized after uploading a source file. |
| `75` | `component_translation_completed` | Component translation completed | All language translations in a component became fully translated after an individual edit. Automatic translation, uploads, and bulk edits do not emit this event. |
| `76` | `applied_enforced_check` | Applied enforced check | A translation was marked as needing editing by an enforced check. |
| `77` | `propagated_change` | Propagated change | A translation edit was propagated to another matching string. |
| `78` | `file_uploaded` | File uploaded | A file was uploaded to a translation. |
| `79` | `extra_flags_updated` | Extra flags updated | Additional source-string flags were updated. |
| `80` | `font_uploaded` | Font uploaded | A font was uploaded. |
| `81` | `font_changed` | Font changed | An uploaded font was changed. |
| `82` | `font_removed` | Font removed | An uploaded font was removed. |
| `83` | `forced_synchronization_of_translations` | Forced synchronization of translations | Translation files were forcibly synchronized with the repository. |
| `84` | `forced_rescan_of_translations` | Forced rescan of translations | Translation files were forcibly rescanned for changes. |
| `85` | `screenshot_removed` | Screenshot removed | A screenshot was removed. |
| `86` | `label_added` | Label added | A label was added to a string. |
| `87` | `label_removed` | Label removed | A label was removed from a string. |
| `88` | `repository_cleanup` | Repository cleanup | The repository working tree was cleaned up. |
| `89` | `source_string_added_in_the_upload` | Source string added in the upload | A source string was added while processing an uploaded file. |
| `90` | `source_string_added_in_the_repository` | Source string added in the repository | A source string was added while synchronizing from the repository. |
| `91` | `project_backed_up` | Project backed up | A project backup was created. |
| `92` | `project_restored` | Project restored | A project was restored from a backup. |
| `93` | `component_restored` | Component restored | A component was restored from a backup. |
| `94` | `user_edit_reverted` | User edit reverted | All selected edits by a user were reverted. |
| `95` | `project_setting_changed` | Project setting changed | A project setting was changed. |
| `96` | `component_setting_changed` | Component setting changed | A component setting was changed. |
| `97` | `user_access_changed` | User access changed | A user’s access permissions were changed. |
| `98` | `workspace_created` | Workspace created | A workspace was created. |
| `99` | `workspace_setting_changed` | Workspace setting changed | A workspace setting was changed. |
| `100` | `project_moved` | Project moved | A project was moved into or out of a workspace. |
| `101` | `remote_repository_updated` | Remote repository updated | A remote repository update was completed. |
| `102` | `remote_repository_update_failed` | Remote repository update failed | Updating a remote repository failed. |
| `103` | `alert_dismissed` | Alert dismissed | A component alert was dismissed. |
| `104` | `alert_reopened` | Alert reopened | A component alert was reopened after its context changed. |
## Customizing list of add-ons
The list of add-ons is configured by [`WEBLATE_ADDONS`](https://docs.weblate.org/en/weblate-2026.10/admin/config.md#std-setting-WEBLATE_ADDONS).
To add another add-on, simply include the absolute class name in this setting.
## Writing add-on
You can write your own add-ons too, create a subclass of
[`weblate.addons.base.BaseAddon`](https://docs.weblate.org/en/weblate-2026.10/contributing/addons.md#weblate.addons.base.BaseAddon) to define the add-on metadata, and
then implement a callback to do the processing.
#### SEE ALSO
[Developing add-ons](https://docs.weblate.org/en/weblate-2026.10/contributing/addons.md)
## 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.
```python
# Copyright © Michal Čihař
#
# SPDX-License-Identifier: GPL-3.0-or-later
"""Example pre commit script."""
from __future__ import annotations
from typing import ClassVar
from django.utils.translation import gettext_lazy
from weblate.addons.events import AddonEvent
from weblate.addons.scripts import BaseScriptAddon
class ExamplePreAddon(BaseScriptAddon):
# Event used to trigger the script
events: ClassVar[set[AddonEvent]] = {
AddonEvent.EVENT_PRE_COMMIT,
}
# Name of the addon, has to be unique
name = "weblate.example.pre"
# Verbose name and long description
verbose = gettext_lazy("Execute script before commit")
description = gettext_lazy("This add-on executes a script.")
# Script to execute
script = "/bin/true"
# File to add in commit (for pre commit event)
# does not have to be set
add_file = "po/{{ language_code }}.po"
```
For installation instructions see [Custom quality checks, add-ons, automatic suggestions and auto-fixes](https://docs.weblate.org/en/weblate-2026.10/admin/customize.md#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:
### WL_VCS
Version control system used.
### WL_REPO
Upstream repository URL.
### WL_PATH
Absolute path to VCS repository.
### WL_BRANCH
Repository branch configured in the current component.
### WL_FILEMASK
File mask for current component.
### WL_TEMPLATE
Filename of template for monolingual translations (can be empty).
### WL_NEW_BASE
Filename of the file used for creating new translations (can be
empty).
### WL_FILE_FORMAT
File format used in current component.
### WL_LANGUAGE
Language of currently processed translation (not available for
component-level hooks).
### WL_PREVIOUS_HEAD
Previous HEAD after update (only available after running the post-update hook).
### WL_COMPONENT_SLUG
Component slug used to construct URL.
### WL_PROJECT_SLUG
Project slug used to construct URL.
### WL_COMPONENT_NAME
Component name.
### WL_PROJECT_NAME
Project name.
### WL_COMPONENT_URL
Component URL.
### WL_ENGAGE_URL
Project engage URL.
#### SEE ALSO
[Component configuration](https://docs.weblate.org/en/weblate-2026.10/admin/projects.md#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:
```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.
### 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 [`ADDON_ACTIVITY_LOG_EXPIRY`](https://docs.weblate.org/en/weblate-2026.10/admin/config.md#std-setting-ADDON_ACTIVITY_LOG_EXPIRY).