Add-ons

New in version 2.19.

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 component.

Hint

You can also configure add-ons using API, DEFAULT_ADDONS, or install_addon.

Built-in add-ons

Automatic translation

New in version 3.9.

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
`filter_type`	Search filter	Available choices: `all` – All strings `nottranslated` – Not translated strings `todo` – Strings needing action `fuzzy` – Strings marked for edit `check:inconsistent` – Failed check: Inconsistent
`auto_source`	Automatic translation source	Available choices: `others` – Other translation components `mt` – Machine translation
`component`	Components	Enter component to use as source, keep blank to use all components in current project.
`engines`	Machine translation engines
`threshold`	Score threshold

Triggers

component update, daily

Automatically translates strings using machine translation or other components.

It is triggered:

When new strings appear in a component.
Once in a month for every component, this can be configured using BACKGROUND_TASKS.

JavaScript localization CDN

New 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

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.

Remove blank strings

New in version 4.4.

Add-on ID: weblate.cleanup.blank
Configuration: This add-on has no configuration.
Triggers: 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: repository pre-commit, repository post-update

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.

Add missing languages

Add-on ID: weblate.consistency.languages
Configuration: This add-on has no configuration.
Triggers: daily, repository post-add

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.
`language_regex`	Language filter	Regular expression to filter translation files against when scanning for filemask.
`copy_addons`	Clone addons from the main component to the newly created ones
`remove`	Remove components for inexistant files
`confirm`	I confirm the above matches look correct

Triggers

repository post-update

Automatically adds or removes project components based on file changes in the version control system.

Triggered each time the VCS is updated, and otherwise similar to the import_project management command. This way you can track multiple translation components within one VCS.

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.

Once you hit Save, a preview of matching components will be presented, from where you can check whether the configuration actually matches your needs:

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

Template markup

Bulk edit

New in version 3.11.

Add-on ID

weblate.flags.bulk

Configuration

`q`	Query
`state`	State to set	Available choices: `-1` – Do not change `10` – Needs editing `20` – Translated `30` – Approved
`add_flags`	Translation flags to add
`remove_flags`	Translation flags to remove
`add_labels`	Labels to add
`remove_labels`	Labels to remove

Triggers

component update

Bulk edit flags, labels, or states of strings.

Automate labeling by starting out with the search query NOT has:label and add labels till all strings have all required labels. Other automated operations for Weblate metadata can also be done.

Examples:

Label new strings automatically
Search query	`NOT has:label`
Labels to add	recent

Marking all App store metadata files changelog entries read-only
Search query	`language:en AND key:changelogs/`
Translation flags to add	`read-only`

Flag unchanged translations as «Needs editing»

New in version 3.1.

Add-on ID: weblate.flags.same_edit
Configuration: This add-on has no configuration.
Triggers: unit post-create

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

Translation states

Flag new source strings as «Needs editing»

Add-on ID: weblate.flags.source_edit
Configuration: This add-on has no configuration.
Triggers: unit post-create

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

Translation states

Flag new translations as «Needs editing»

Add-on ID: weblate.flags.target_edit
Configuration: This add-on has no configuration.
Triggers: unit post-create

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

Translation states

Statistics generator

Add-on ID

weblate.generate.generate

Configuration

`filename`	Name of generated file
`template`	Content of generated file

Triggers

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 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

Template markup

Pseudolocale generation

Add-on ID

weblate.generate.pseudolocale

Configuration

`source`	Source strings
`target`	Target translation
`prefix`	String prefix
`suffix`	String suffix

Triggers

component update, 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.

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: repository pre-commit

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@cihar.com>, 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: repository post-add, daily

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

65535 – Only wrap lines at newlines

-1 – No line wrapping

Triggers

storage post-load

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: repository post-add, daily

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.

Triggers

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.

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

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.

Triggered whenever new changes are pulled from the upstream repository. 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 one

language – Per language

file – Per file

author – Per author

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

repository post-commit

Squash Git commits prior to pushing changes.

Git commits can be squashed prior to pushing changes in one of the following modes:

New in version 3.4.

All commits into one
Per language
Per file

New in version 3.5.

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.

New in version 4.1.

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 – Spaces

tabs – Tabs

Triggers

storage post-load

Allows adjusting JSON output behavior, for example indentation or sorting.

Formats the Java properties file

Add-on ID: weblate.properties.sort
Configuration: This add-on has no configuration.
Triggers: repository pre-commit

Sorts the Java properties file.

Stale comment removal

New in version 3.7.

Add-on ID

weblate.removal.comments

Configuration

age

Days to keep

Triggers

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

New in version 3.7.

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

daily

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

New in version 3.9.

Add-on ID: weblate.resx.update
Configuration: This add-on has no configuration.
Triggers: 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 if you only want to remove stale translation keys.

Customize YAML output

New in version 3.10.2.

Add-on ID

weblate.yaml.customize

Configuration

indent

YAML indentation

width

Long lines wrapping

Available choices:

80 – Wrap lines at 80 chars

100 – Wrap lines at 100 chars

120 – Wrap lines at 120 chars

180 – Wrap lines at 180 chars

65535 – No line wrapping

line_break

Line breaks

Available choices:

dos – DOS (\r\n)

unix – UNIX (\n)

mac – MAC (\r)

Triggers

storage post-load

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 addon metadata, and then implement a callback to do the processing.

See also

Developing addons

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 © 2012 - 2021 Michal Čihař <michal@cihar.com>
#
# This file is part of Weblate <https://weblate.org/>
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <https://www.gnu.org/licenses/>.
#
"""Example pre commit script."""


from django.utils.translation import gettext_lazy as _

from weblate.addons.events import EVENT_PRE_COMMIT
from weblate.addons.scripts import BaseScriptAddon


class ExamplePreAddon(BaseScriptAddon):
    # Event used to trigger the script
    events = (EVENT_PRE_COMMIT,)
    # Name of the addon, has to be unique
    name = "weblate.example.pre"
    # Verbose name and long descrption
    verbose = _("Execute script before commit")
    description = _("This addon 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, addons 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: New in version 2.11.

Repository branch configured in the current component.

WL_FILEMASK: Filemask for current component.

WL_TEMPLATE: Filename of template for monolingual translations (can be empty).

WL_NEW_BASE: New in version 2.14.

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: New in version 3.9.

Component slug used to construct URL.

WL_PROJECT_SLUG: New in version 3.9.

Project slug used to construct URL.

WL_COMPONENT_NAME: New in version 3.9.

Component name.

WL_PROJECT_NAME: New in version 3.9.

Project name.

WL_COMPONENT_URL: New in version 3.9.

Component URL.

WL_ENGAGE_URL: New in version 3.9.

Project engage URL.

See also

Component configuration

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.