Continuous localization - Weblate 5.17.1 documentation

Continuous localization - Weblate 5.17.1 documentation
Skip to content
User docs
Weblate basics
Registration and user profile
Translating using Weblate
Downloading and uploading translations
Glossary
Checks and fixups
Searching
Translation workflows
Frequently Asked Questions
Version control integration
Weblate’s REST API
Weblate Client
Weblate’s Python API
Application developer guide
Starting with internationalization
Migrating to Weblate
Integrating with Weblate
Translating software using GNU gettext
Multi-platform localization
Translating documentation using Sphinx
Translating HTML and JavaScript using Weblate CDN
Localization libraries and packages
Translation component alerts
Building a translators community
Managing translations
Reviewing strings
Building the translation community
Translation progress reporting
Success stories
Administrator docs
Configuration instructions
Weblate deployments
Upgrading Weblate
Backing up and moving Weblate
Authentication
Two-factor authentication
Access control
Translation projects
Language definitions
Continuous localization
Licensing translations
Translation process
Checks and fixups
Automatic suggestions
Add-ons
Translation Memory
Configuration
Sample configuration
Management commands
Announcements
Component Lists
Optional Weblate modules
Customizing Weblate
Management interface
Getting support for Weblate
Contributor docs
Contributing to Weblate
Weblate Contributor Communication Guidelines
Starting contributing code to Weblate
Weblate source code
Debugging Weblate
Contribute to Weblate documentation
Weblate internals
Developing add-ons
Weblate frontend
Reporting issues in Weblate
Weblate testsuite and continuous integration
Local testing of Weblate modules
Testing repository
Data schemas
Releasing Weblate
Contributing to Weblate modules
Subprojects and embedded code
About Weblate
Code of Conduct
Weblate license
Weblate Trademark Guidelines
Secure Weblate
Security, privacy and compliance
Dependencies
Vulnerability and incident handling
Incident response plan for Weblate
Password security
Disaster recovery plan
Weblate threat model
Privacy regulations compliance
US controls compliance
Localization Threat Model
Data residency
File formats
Localization file formats
Android string resources
Apple iOS strings
App store metadata files
ARB File
AsciiDoc files
Catkeys file
Compose Multiplatform resources
CSV files
DTD files
Excel Open XML
Flat XML files
Fluent format
Format.JS JSON file
GNU gettext PO (Portable Object)
go-i18n JSON files
gotext JSON files
GWT properties
HTML files
i18next JSON files
IDML Format
INI translations
Inno Setup INI translations
Java properties
Joomla translations
JSON files
Laravel PHP strings
Markdown files
draggable/i18n lang files
Mobile Kotlin resources
Nextcloud Apps JSON files
OpenDocument Format
PHP strings
Qt Linguist .ts
JavaScript Resource Files (RESJSON)
ResourceDictionary files
.NET resource files (RESX, RESW)
Ruby YAML files
Stringsdict format
Subtitle files
TermBase eXchange format
TOML
Text files
WebExtension JSON
Windows RC files
WixLocalization file
XLIFF 1.1 and 1.2
XLIFF 2.0
YAML files
Change history
Weblate 5.17.1
Weblate 5.17
Weblate 5.16.2
Weblate 5.16.1
Weblate 5.16
Weblate 5.15.2
Weblate 5.15.1
Weblate 5.15
Weblate 5.14.3
Weblate 5.14.2
Weblate 5.14.1
Weblate 5.14
Weblate 5.13.3
Weblate 5.13.2
Weblate 5.13.1
Weblate 5.13
Weblate 5.12.2
Weblate 5.12.1
Weblate 5.12
Weblate 5.11.4
Weblate 5.11.3
Weblate 5.11.2
Weblate 5.11.1
Weblate 5.11
Weblate 5.10.4
Weblate 5.10.3
Weblate 5.10.2
Weblate 5.10.1
Weblate 5.10
Weblate 5.9.2
Weblate 5.9.1
Weblate 5.9
Weblate 5.8.4
Weblate 5.8.3
Weblate 5.8.2
Weblate 5.8.1
Weblate 5.8
Weblate 5.7.2
Weblate 5.7.1
Weblate 5.7
Weblate 5.6.2
Weblate 5.6.1
Weblate 5.6
Weblate 5.5.5
Weblate 5.5.4
Weblate 5.5.3
Weblate 5.5.2
Weblate 5.5.1
Weblate 5.5
Weblate 5.4.3
Weblate 5.4.2
Weblate 5.4.1
Weblate 5.4
Weblate 5.3.1
Weblate 5.3
Weblate 5.2.1
Weblate 5.2
Weblate 5.1.1
Weblate 5.1
Weblate 5.0.2
Weblate 5.0.1
Weblate 5.0
Weblate 4.x series
Weblate 3.x series
Weblate 2.x series
Weblate 1.x series
Weblate 0.x series
Indices and tables
Index
Module Index
View this page
Edit this page
Continuous localization
There is infrastructure in place so that your translation closely follows
development. This way translators can work on translations the entire time,
instead of working through huge amount of new text just prior to release.
See also
Integrating with Weblate
describes basic ways to integrate your development
with Weblate.
This is the process:
Developers make changes and push them to the VCS repository.
Optionally the translation files are updated, see
Introducing new strings
Weblate pulls changes from the VCS repository, parses translation files and updates its database, see
Updating repositories
Translators submit translations using the Weblate web interface, or upload offline changes.
Once the translators are finished, Weblate commits the changes to the local repository (see
Lazy commits
).
Changes are pushed back to the upstream repository (see
Pushing changes from Weblate
).
digraph translations {
graph [fontname = "sans-serif", fontsize=10, ranksep=0.6, newrank=true];
node [fontname = "sans-serif", fontsize=10, margin=0.15];
edge [fontname = "sans-serif", fontsize=10];

subgraph cluster_codehosting {
rank=same;
graph [color=lightgrey,
label="Upstream code hosting",
style=filled
];

"VCS repository" [shape=cylinder];

subgraph cluster_weblate {
rank=same;
graph [color=lightgrey,
label="Weblate",
style=filled
];

repo [label="Weblate repository",
shape=cylinder];
database [label=Database,
shape=cylinder];

"Developers" [shape=box, fillcolor="#144d3f", fontcolor=white, style=filled];
"Translators" [shape=box, fillcolor="#144d3f", fontcolor=white, style=filled];

"Developers" -> "VCS repository" [label=" 1. Push "];

"VCS repository" -> "VCS repository" [label=" 2. Updating translations ", style=dotted];

"VCS repository" -> repo [label=" 3. Pull "];
repo -> database [label=" 3. Parse translations "];

"database" -> repo [label=" 5. Commit changes "];

"Translators" -> "database" [label=" 4. Translate "];

"repo" -> "VCS repository" [label=" 6. Push repository "];
Hint
Upstream code hosting is not necessary, you can use Weblate with
Local files
where there is only the repository inside Weblate.
Updating repositories
You should set up some way of updating backend repositories from their
source.
Use
Notification hooks
to integrate with most of common code hosting services:
Automatically receiving changes from GitHub
Automatically receiving changes from GitLab
Automatically receiving changes from Bitbucket
Automatically receiving changes from Pagure
Automatically receiving changes from Azure Repos
Automatically receiving changes from Gitea Repos
You must also
Enable hooks
for this to work.
Manually trigger update either in the repository management or using
Weblate’s REST API
or
Weblate Client
Enable
AUTO_UPDATE
to automatically update all components on your Weblate instance
Execute
updategit
(with selection of project or
--all
to update all)
Whenever Weblate updates the repository, the post-update addons will be
triggered, see
Add-ons
Avoiding merge conflicts
The merge conflicts from Weblate arise when same file was changed both in
Weblate and outside it. Depending on the situation, there are several approaches that might help here:
Avoiding merge conflicts by changing translation files in Weblate only
Avoiding merge conflicts by locking Weblate while doing outside changes
Avoiding merge conflicts by focusing on Git operations
Avoiding merge conflicts by changing translation files in Weblate only
Avoiding edits outside Weblate is easy with monolingual files — you can add new strings
within Weblate and leave whole editing of the files there. For bilingual files,
there is usually some kind of message extraction process to generate
translatable files from the source code. In some cases, this can be split into
two parts:
The extraction generates template (for example gettext POT is generated using
xgettext
).
Further process merges it into actual translations (the gettext PO files are updated using
msgmerge
).
You can perform the second step within Weblate and it
will ensure that all pending changes are included before this operation.
Avoiding merge conflicts by locking Weblate while doing outside changes
Integrating Weblate into your updating process so that it flushes changes before updating the files outside Weblate can be achieved by using
Weblate’s REST API
to force Weblate to
push all pending changes and lock the translation while you are doing changes
on your side.
The script for doing updates can look like this:
# Lock Weblate translation
wlc
lock
# Push changes from Weblate to upstream repository
wlc
push
# Pull changes from upstream repository to your local copy
git
pull
# Update translation files, this example is for Django
./manage.py
makemessages
--keep-pot
-a
git
commit
-m
'Locale updates'
--
locale
# Push changes to upstream repository
git
push
# Tell Weblate to pull changes (not needed if Weblate follows your repo
# automatically)
wlc
pull
# Unlock translations
wlc
unlock
If you have multiple components sharing the same repository, you need to lock them
all separately:
wlc
lock
foo/bar
wlc
lock
foo/baz
wlc
lock
foo/baj
Note
The example uses
Weblate Client
, which needs configuration (API keys) to be
able to control Weblate remotely. You can also achieve this using any HTTP
client instead of
Weblate Client
, for example curl, see
Weblate’s REST API
Repository maintenance
The
Repository maintenance
view shows repository status for a
project, component, or translation and lets privileged users run maintenance
operations from the user interface.
The same actions can also be triggered using
Weblate’s REST API
or, for the supported
subset,
Weblate Client
Availability of individual actions depends on permissions, the configured
version control system, whether pushing is configured, and whether the selected
object can be locked.
Action
What it does
Typical use
Commit
Commits pending changes stored in Weblate to the local repository.
Flush pending Weblate changes before doing repository work elsewhere.
Push
Pushes committed local repository changes to the configured upstream.
Send committed translations upstream when automatic push is disabled or delayed.
Update
Fetches upstream changes and integrates them using the component’s configured
Merge style
Bring Weblate in sync with upstream using the default integration strategy.
Update with merge
Fetches upstream changes and integrates them with an explicit merge.
Override the default merge style for a single update.
Update with rebase
Fetches upstream changes and rebases local Weblate commits on top of upstream.
Keep history linear when that matches your workflow.
Update with merge without fast-forward
Fetches upstream changes and creates an explicit merge commit even when a fast-forward would be possible.
Preserve merge commits for auditing or branch-management reasons.
Lock
Unlock
Prevents or allows translators to make further changes in Weblate.
Freeze translation changes while doing repository maintenance outside Weblate.
Reset and discard
Resets Weblate’s local repository to upstream and discards pending Weblate changes.
Use when upstream should overwrite the local Weblate repository state.
Reset and reapply
Resets Weblate’s local repository to upstream while preserving pending translations. See
Reset and reapply recovery behavior
Recover from diverged history while keeping pending Weblate translations.
Cleanup
Removes untracked files and stale branches from the local repository checkout.
Clean up leftover files or stale repository state in Weblate’s checkout.
Synchronize
Forces Weblate to write all known translations back to the repository files.
Repair cases where repository files became out of sync with the database state.
Rescan
Re-reads translation files from the local repository into Weblate.
Import file changes after manual repository work or file creation.
Reset and reapply recovery behavior
The
Reset and reapply
operation keeps pending translations from
Weblate while resetting the local repository state to match upstream.
The operation can restore pending translations only when the target language
files still exist after the reset or when Weblate can create them for the
component, for example using a valid
Template for new translations
If neither of these conditions is met, Weblate keeps the pending changes in its
database and reports a recovery error instead of failing later with a generic
parse error.
Avoiding merge conflicts by focusing on Git operations
Even when Weblate is the single source of the changes in the translation files,
conflicts can appear when using
Squash Git commits
add-on,
Merge style
is configured to
Rebase
, or you are
squashing commits outside of Weblate (for example, when merging a pull request).
The reason for merge conflicts is different in this case - there are changes in
Weblate which happened after you merged Weblate commits. This typically happens
if merging is not automated and waits for days or weeks for a human to review
them. Git is then sometimes no longer able to identify upstream changes as
matching the Weblate ones and refuses to perform a rebase.
To approach this, you either need to minimize the amount of pending changes in
Weblate when you merge a pull request, or avoid the conflicts completely by not
squashing changes.
Here are few options how to avoid that:
Do not use neither
Squash Git commits
nor squashing at merge time. This is the root cause why git doesn’t recognize changes after merging.
Let Weblate commit pending changes before merging. This will update the pull request with all its changes, and both repositories will be in sync.
Use the review features in Weblate (see
Translation workflows
) so that you can automatically merge GitHub pull requests after CI passes.
Use locking in Weblate to avoid changes while GitHub pull request is in review.
See also
Weblate Client
Automatically receiving changes from GitHub
Weblate comes with native support for GitHub.
If you are using Hosted Weblate, the recommended approach is to install the
Weblate app
. The app delivers GitHub
notifications to Hosted Weblate, so you do not need to configure a separate
Webhook
in GitHub. It does not by itself grant Hosted Weblate write
access to the repository, though. To push changes back, you still need to add
the Hosted Weblate
weblate
GitHub user as a collaborator with write
access, see
Accessing repositories from Hosted Weblate
If you are not using the app, add the Weblate Webhook in the repository
settings (
Webhooks
) to receive notifications on every push to a
GitHub repository, as shown on the image below:
The
Payload URL
consists of your Weblate URL appended by
/hooks/github/
, for example for the Hosted Weblate service, this is
You can leave other values at default settings (Weblate can handle both
content types and consumes just the
push
event).
See also
POST
/hooks/github/
Accessing repositories from Hosted Weblate
Automatically receiving changes from Bitbucket
Weblate has support for Bitbucket webhooks, add a webhook
which triggers upon repository push, with destination to
/hooks/bitbucket/
URL
on your Weblate installation (for example
).
See also
POST
/hooks/bitbucket/
Accessing repositories from Hosted Weblate
Automatically receiving changes from GitLab
Weblate has support for GitLab hooks, add a project webhook
with destination to
/hooks/gitlab/
URL on your Weblate installation
(for example
).
Troubleshooting
Check
GitLab webhook request history
if webhooks are delivered.
The response payload contains information about matched components.
See also
POST
/hooks/gitlab/
Accessing repositories from Hosted Weblate
Automatically receiving changes from Pagure
Weblate has support for Pagure hooks, add a webhook
with destination to
/hooks/pagure/
URL on your Weblate installation (for
example
). This can be done in
Activate Web-hooks
under
Project options
See also
POST
/hooks/pagure/
Accessing repositories from Hosted Weblate
Automatically receiving changes from Azure Repos
Weblate has support for Azure Repos webhooks, add a webhook for
Code pushed
event with destination to
/hooks/azure/
URL on your
Weblate installation (for example
).
This can be done in
Service hooks
under
Project
settings
See also
Web hooks in Azure DevOps manual
POST
/hooks/azure/
Accessing repositories from Hosted Weblate
Automatically receiving changes from Gitea Repos
Weblate has support for Gitea webhooks, add a
Gitea Webhook
for
Push events
event with destination to
/hooks/gitea/
URL on your
Weblate installation (for example
).
This can be done in
Webhooks
under repository
Settings
See also
Webhooks in Gitea manual
POST
/hooks/gitea/
Accessing repositories from Hosted Weblate
Automatically receiving changes from Forgejo Repos
Weblate has support for Forgejo webhooks, add a
Forgejo Webhook
for
Push events
event with destination to
/hooks/forgejo/
URL on your
Weblate installation (for example
).
This can be done in
Webhooks
under repository
Settings
See also
Webhooks in Forgejo documentation
POST
/hooks/forgejo/
Accessing repositories from Hosted Weblate
Automatically receiving changes from Gitee Repos
Weblate has support for Gitee webhooks, add a
WebHook
for
Push
event with destination to
/hooks/gitee/
URL on your
Weblate installation (for example
).
This can be done in
WebHooks
under repository
Management
See also
Webhooks in Gitee manual
POST
/hooks/gitee/
Accessing repositories from Hosted Weblate
Automatically updating repositories nightly
Weblate automatically fetches remote repositories nightly to improve
performance when merging changes later. You can optionally turn this into doing
nightly merges as well, by enabling
AUTO_UPDATE
Pushing changes from Weblate
Each translation component can have a push URL set up (see
Repository push URL
), and in that case Weblate will be able to push change to
the remote repository. Weblate can be also be configured to automatically push
changes on every commit (this is default, see
Push on commit
).
If you do not want changes to be pushed automatically, you can do that manually
under
Repository maintenance
or using the API via
wlc
push
The push options differ based on the
Version control integration
used, more details are found in that chapter.
In case you do not want direct pushes by Weblate, there is support for
GitHub pull requests
GitLab merge requests
Gitea pull requests
Pagure merge requests
Azure DevOps pull requests
or
Gerrit
reviews, you can activate these by
choosing
GitHub
GitLab
Gitea
Gerrit
Azure DevOps
, or
Pagure
as
Version control system
in
Component configuration
Overall, following options are available with Git, Mercurial, GitHub, GitLab,
Gitea, Pagure, Azure DevOps, Bitbucket Data Center and Bitbucket Cloud:
Desired setup
Version control system
Repository push URL
Push branch
No push
Git
empty
empty
Push directly
Git
SSH URL
empty
Push to separate branch
Git
SSH URL
Branch name
No push
Mercurial
empty
empty
Push directly
Mercurial
SSH URL
empty
Push to separate branch
Mercurial
SSH URL
Branch name
GitHub pull request from fork
GitHub pull requests
empty
empty
GitHub pull request from branch
GitHub pull requests
SSH URL
Branch name
GitLab merge request from fork
GitLab merge requests
empty
empty
GitLab merge request from branch
GitLab merge requests
SSH URL
Branch name
Gitea merge request from fork
Gitea pull requests
empty
empty
Gitea merge request from branch
Gitea pull requests
SSH URL
Branch name
Pagure merge request from fork
Pagure merge requests
empty
empty
Pagure merge request from branch
Pagure merge requests
SSH URL
Branch name
Azure DevOps pull request from fork
Azure DevOps pull requests
empty
empty
Azure DevOps pull request from branch
Azure DevOps pull requests
SSH URL
Branch name
Bitbucket Data Center pull request from fork
Bitbucket Data Center pull requests
empty
empty
Bitbucket Data Center pull request from branch
Bitbucket Data Center pull requests
SSH URL
Branch name
Bitbucket Cloud pull request from fork
Bitbucket Cloud pull requests
empty
empty
Bitbucket Cloud pull request from branch
Bitbucket Cloud pull requests
SSH URL
Branch name
Can be empty in case
Source code repository
supports pushing.
Note
You can also enable automatic pushing of changes after Weblate commits, this can be done in
Push on commit
See also
See
Accessing repositories
for setting up SSH keys, and
Lazy commits
for
info about when Weblate decides to commit changes.
Protected branches
If you are using Weblate on protected branch, you can configure it to use pull
requests and perform actual review on the translations (what might be
problematic for languages you do not know). An alternative approach is to waive
this limitation for the Weblate push user.
For example on GitHub this can be done in the repository configuration:
Interacting with others
Weblate makes it easy to interact with others using its API.
See also
Weblate’s REST API
Lazy commits
The behaviour of Weblate is to group commits from the same author into one
commit if possible. This greatly reduces the number of commits, however you
might need to explicitly tell it to do the commits in case you want to get the
VCS repository in sync, e.g. for merge (this is by default allowed for the
Managers
group, see
List of privileges
).
The changes in this mode are committed once any of the following conditions are
fulfilled:
Somebody else changes an already changed string.
A merge from upstream occurs.
An explicit commit is requested.
A file download is requested.
Change is older than period defined as
Age of changes to commit
on
Component configuration
Hint
Commits are created for every component. So in case you have many components
you will still see lot of commits. You might utilize
Squash Git commits
add-on in that case.
If you want to commit changes more frequently and without checking of age, you
can schedule a regular task to perform a commit. This can be done using
Periodic Tasks
in
The Django admin interface
. First create desired
Interval
(for example 120 seconds). Then add new periodic task and
choose
weblate.trans.tasks.commit_pending
as
Task
with
{"hours":
0}
as
Keyword Arguments
and desired interval.
Processing repository with scripts
The way to customize how Weblate interacts with the repository is
Add-ons
. Consult
Executing scripts from add-on
for info on how to execute
external scripts through add-ons.
Keeping translations same across components
Once you have multiple translation components, you might want to ensure that
the same strings have same translation. This can be achieved at several levels.
Translation propagation
With
Allow translation propagation
enabled (what is the default, see
Component configuration
), all new translations are automatically done in all
components with matching strings. Such translations are properly credited to
currently translating user in all components.
Propagation preconditions:
All components have to reside in a single project (linking component is not enough).
Enable
Allow translation propagation
to automatically reuse translations for matching strings.
The translation propagation requires the key to be match for monolingual
translation formats, so keep that in mind when creating translation keys.
The strings are propagated while translating, strings loaded from the
repository are not propagated.
Tip
This feature currently has limitations, and we want to make it more
universal. Please share your feedback at
Consistency check
The
Inconsistent
check fires whenever the strings are different.
You can utilize this to review such differences manually and choose the right
translation.
Automatic translation
Automatic translation based on different components can be way to synchronize
the translations across components. You can either trigger it manually (see
Automatic translation
) or make it run automatically on repository update
using add-on (see
Automatic translation
).
On this page
Continuous localization
Updating repositories
Avoiding merge conflicts
Avoiding merge conflicts by changing translation files in Weblate only
Avoiding merge conflicts by locking Weblate while doing outside changes
Repository maintenance
Reset and reapply recovery behavior
Avoiding merge conflicts by focusing on Git operations
Automatically receiving changes from GitHub
Automatically receiving changes from Bitbucket
Automatically receiving changes from GitLab
Automatically receiving changes from Pagure
Automatically receiving changes from Azure Repos
Automatically receiving changes from Gitea Repos
Automatically receiving changes from Forgejo Repos
Automatically receiving changes from Gitee Repos
Automatically updating repositories nightly
Pushing changes from Weblate
Protected branches
Interacting with others
Lazy commits
Processing repository with scripts
Keeping translations same across components
Translation propagation
Consistency check
Automatic translation