Add-ons¶
Add-ons provide ways to customize and automate the translation workflow. Admins can add and manage add-ons from the Manage ↓ Add-ons menu of each respective translation project or component. Add-ons can be also installed site-wide in Management interface.
Hint
You can also configure add-ons using API,
DEFAULT_ADDONS
, or install_addon
.
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
.
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-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.
Storage post-load¶
Triggered when file is parsed by Weblate.
Unit post-save¶
Triggered just after the string is saved.
Unit pre-create¶
Triggered just after the newly created string is saved.
Built-in add-ons¶
Automatic translation¶
- Add-on ID:
weblate.autotranslate.autotranslate
- Configuration:
mode
Automatic translation mode
Available choices:
suggest
– Add as suggestiontranslate
– Add as translationfuzzy
– Add as “Needing edit”filter_type
Search filter
Please note that translating all strings will discard all existing translations.
Available choices:
all
– All stringsnottranslated
– Untranslated stringstodo
– Unfinished stringsfuzzy
– Strings marked for editcheck:inconsistent
– Failing check: Inconsistentcheck:translated
– Failing check: Has been translatedauto_source
Source of automated translations
Available choices:
others
– Other translation componentsmt
– Machine translationcomponent
Component
Enter slug of a component to use as source, keep blank to use all components in the current project.
engines
Machine translation engines
threshold
Score threshold
- Triggers:
Automatically translates strings using machine translation or other components.
JavaScript localization CDN¶
Added in version 4.2.
- Add-on ID:
weblate.cdn.cdnjs
- Configuration:
threshold
Translation threshold
Threshold for inclusion of translations.
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, Daily, Repository post-commit, 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 for more details.
Note
This add-on requires additional configuration on the Weblate server.
LOCALIZE_CDN_PATH
configures where generated files will be
written (on a filesystem), and 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/
.
Remove blank strings¶
Added in version 4.4.
- Add-on ID:
weblate.cleanup.blank
- Configuration:
This add-on has no configuration.
- Triggers:
Add-on installation, Repository post-commit, 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).
Cleanup translation files¶
- Add-on ID:
weblate.cleanup.generic
- Configuration:
This add-on has no configuration.
- Triggers:
Add-on installation, Repository post-update, 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, Windows RC files, or OpenDocument Format) this also brings the translation file in sync with the base file.
Add missing languages¶
- Add-on ID:
weblate.consistency.languages
- Configuration:
This add-on has no configuration.
- Triggers:
Ensures a consistent set of languages is used for all components within a project.
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.
Component discovery¶
- Add-on ID:
weblate.discovery.discovery
- Configuration:
match
Regular expression to match translation files against
file_format
File format
name_template
Customize the component name
base_file_template
Define the monolingual base filename
Leave empty for bilingual translation files.
new_base_template
Define the base file for new translations
Filename of file used for creating new translations. For gettext choose .pot file.
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.
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
confirm
I confirm the above matches look correct
- Triggers:
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. Some examples for common use cases can be found in the add-on help section.
The regular expression to match translation files has to contain two named groups to match component and language. All named groups in the regular expression can be used as variables in the template fields.
You can use Django template markup in all filename fields, for example:
{{ component }}
Component filename match
{{ 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¶
One folder per language¶
One folder per language containing translation files for components.
- Regular expression:
(?P<language>[^/.]*)/(?P<component>[^/]*)\.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<language>[^/.]*)/LC_MESSAGES/(?P<component>[^/]*)\.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<component>[^/]*)\.(?P<language>[^/.]*)\.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<language>[^/.]*)/(?P<component>[^/]*)/(?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<language>[^/.]*)/strings-(?P<component>[^/]*)\.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<originalHierarchy>.+/)(?P<component>[^/]*)/src/main/resources/ApplicationResources_(?P<language>[^/.]*)\.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. 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 field (in Manage ↓ Settings ↓
Version control system) of each respective component.
This saves time with configuration and system resources too.
See also
Bulk edit¶
- Add-on ID:
weblate.flags.bulk
- Configuration:
q
Query
state
State to set
Available choices:
-1
– Do not change10
– Needs editing20
– Translated30
– Approvedadd_flags
Translation flags to add
remove_flags
Translation flags to remove
add_labels
Labels to add
remove_labels
Labels to remove
- Triggers:
Bulk edit flags, labels, or states of strings.
Examples:
Search query |
|
---|---|
Labels to add |
recent |
Search query |
|
---|---|
Translation flags to add |
|
Search query |
|
---|---|
Translation flags to add |
|
Flag unchanged translations as “Needs editing”¶
- Add-on ID:
weblate.flags.same_edit
- Configuration:
This add-on has no configuration.
- Triggers:
Whenever a new translatable string is imported from the VCS and it matches a source string, it is flagged as needing editing in Weblate. Especially useful for file formats that include source strings for untranslated strings.
Hint
You might also want to tighthen the Unchanged translation check by adding
strict-same
flag to Translation flags.
See also
Flag new source strings as “Needs editing”¶
- Add-on ID:
weblate.flags.source_edit
- Configuration:
This add-on has no configuration.
- Triggers:
Whenever a new source string is imported from the VCS, it is flagged as needing editing in Weblate. This way you can easily filter and edit source strings written by the developers.
See also
Flag new translations as “Needs editing”¶
- Add-on ID:
weblate.flags.target_edit
- Configuration:
This add-on has no configuration.
- Triggers:
Whenever a new translatable string is imported from the VCS, it is flagged as needing editing in Weblate. This way you can easily filter and edit translations created by the developers.
See also
Fill read-only strings with source¶
Added in version 4.18.
- Add-on ID:
weblate.generate.fill_read_only
- Configuration:
This add-on has no configuration.
- Triggers:
Fills in translation of read-only strings with source string.
Statistics generator¶
- Add-on ID:
weblate.generate.generate
- Configuration:
filename
Name of generated file
template
Content of generated file
- Triggers:
Generates a file containing detailed info about the translation status.
You can use a Django template in both filename and content, see Template markup for a detailed markup description.
For example generating a summary file for each translation:
- Name of generated file
locale/{{ language_code }}.json
- Content
{ "language": "{{ language_code }}", "strings": "{{ stats.all }}", "translated": "{{ stats.translated }}", "last_changed": "{{ stats.last_changed }}", "last_author": "{{ stats.last_author }}", }
See also
Prefill translation with source¶
Added in version 4.11.
- Add-on ID:
weblate.generate.prefill
- Configuration:
This add-on has no configuration.
- Triggers:
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.
Pseudolocale generation¶
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
Fixed string prefix
var_prefix
Variable string prefix
suffix
Fixed string suffix
var_suffix
Variable string suffix
var_multiplier
Variable part multiplier
How many times to repeat the variable part depending on the length of the source string.
include_readonly
Include read-only strings
- Triggers:
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 parts are repeated by length of the
text multiplied by the multiplier. For example Hello world
with variable
suffix _
and variable multiplier of 1 becomes Hello world___________
-
the suffix is repeated once for each character in the source string.
The strings will be generated using following pattern:
Fixed string prefix Variable string prefix Source string Variable string suffix Fixed string suffix
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.
Contributors in comment¶
- Add-on ID:
weblate.gettext.authors
- Configuration:
This add-on has no configuration.
- Triggers:
Updates the comment part of the PO file header to include contributor names and years of contributions.
The PO file header will look like this:
# Michal Čihař <michal@weblate.org>, 2012, 2018, 2019, 2020.
# Pavel Borecki <pavel@example.com>, 2018, 2019.
# Filip Hron <filip@example.com>, 2018, 2019.
# anonymous <noreply@weblate.org>, 2019.
Update ALL_LINGUAS variable in the “configure” file¶
- Add-on ID:
weblate.gettext.configure
- Configuration:
This add-on has no configuration.
- Triggers:
Updates the ALL_LINGUAS variable in configure
, configure.in
or any
configure.ac
files, when a new translation is added.
Customize gettext output¶
- Add-on ID:
weblate.gettext.customize
- Configuration:
width
Long lines wrapping
By default gettext wraps lines at 77 characters and at newlines. With the –no-wrap parameter, wrapping is only done at newlines.
Available choices:
77
– Wrap lines at 77 characters and at newlines (xgettext default)65535
– Only wrap lines at newlines (like ‘xgettext –no-wrap’)-1
– No line wrapping- Triggers:
Allows customization of gettext output behavior, for example line wrapping.
It offers the following options:
Wrap lines at 77 characters and at newlines
Only wrap lines at newlines
No line wrapping
Note
By default gettext wraps lines at 77 characters and at newlines.
With the --no-wrap
parameter, wrapping is only done at newlines.
Update LINGUAS file¶
- Add-on ID:
weblate.gettext.linguas
- Configuration:
This add-on has no configuration.
- Triggers:
Updates the LINGUAS file when a new translation is added.
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:
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.
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)¶
- Add-on ID:
weblate.gettext.msgmerge
- Configuration:
previous
Keep previous msgids of translated strings
no_location
Remove locations of translated strings
fuzzy
Use fuzzy matching
- Triggers:
Updates all PO files (as configured by File mask) to match the POT file (as configured by Template for new translations) using msgmerge.
Most msgmerge command-line options can be set up through the add-on configuration.
Squash Git commits¶
- Add-on ID:
weblate.git.squash
- Configuration:
squash
Commit squashing
Available choices:
all
– All commits into onelanguage
– Per languagefile
– Per fileauthor
– Per authorappend_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:
Squash Git commits prior to pushing changes.
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
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¶
- Add-on ID:
weblate.json.customize
- Configuration:
sort_keys
Sort JSON keys
indent
JSON indentation
style
JSON indentation style
Available choices:
spaces
– Spacestabs
– Tabs- Triggers:
Allows adjusting JSON output behavior, for example indentation or sorting.
Format the Java properties file¶
- Add-on ID:
weblate.properties.sort
- Configuration:
case_sensitive
Enable case-sensitive key sorting
- Triggers:
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:
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. This field has no effect with voting turned off.
- Triggers:
Set a timeframe for removal of suggestions.
Can be very useful in connection with suggestion voting (see 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:
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 if you only want to remove stale translation keys.
Customize XML output¶
Added in version 4.15.
- Add-on ID:
weblate.xml.customize
- Configuration:
closing_tags
Include closing tag for blank XML tags
- Triggers:
Allows adjusting XML output behavior, for example closing tags.
Customize YAML output¶
- Add-on ID:
weblate.yaml.customize
- Configuration:
indent
YAML indentation
width
Long lines wrapping
Available choices:
80
– Wrap lines at 80 chars100
– Wrap lines at 100 chars120
– Wrap lines at 120 chars180
– Wrap lines at 180 chars65535
– No line wrappingline_break
Line breaks
Available choices:
dos
– DOS (\r\n)unix
– UNIX (\n)mac
– MAC (\r)- Triggers:
Allows adjusting YAML output behavior, for example line-length or newlines.
Customizing list of add-ons¶
The list of add-ons is configured by 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
to define the add-on metadata, and
then implement a callback to do the processing.
See also
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.
# Copyright © Michal Čihař <michal@weblate.org>
#
# SPDX-License-Identifier: GPL-3.0-or-later
"""Example pre commit script."""
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: 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 and auto-fixes.
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
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:
#! /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.
The logs can be pruned after a certain time interval by configuring the ADDON_ACTIVITY_LOG_EXPIRY
.