Weblate provides you with a great infrastructure for translation to closely follow your development. This way translators can work on translations the entire time and are not forced to translate a huge amount of new texts before release.
The complete process can be described in following steps:
- Developers make some changes and push them to the VCS repository.
- Optionally the translation files are updated (this depends on the file format, see Why does Weblate still show old translation strings when I’ve updated the template?).
- Weblate pulls changes from the VCS repository, see Updating repositories.
- Once Weblate detects changes in translations, translators will be notified based on their subscription settings.
- Translators make translations using Weblate web interface.
- Once translators are done, Weblate commits the changes to the local repository (see Lazy commits) and pushes them back if it has permissions to do that (see Pushing changes).
You should set up some way how backend repositories are updated from their
source. You can either use hooks (see Notification hooks) or just regularly run
updategit (with selection of project or –all for updating all).
Whenever Weblate updates the repository, the Post-update script hooks are executed.
With Gettext po files, you might be often bitten by conflict in PO file
headers. To avoid it, you can use shipped merge driver
examples/git-merge-gettext-po). To use it just put following
configuration to your
[merge "merge-gettext-po"] name = merge driver for gettext po files driver = /path/to/weblate/examples/git-merge-gettext-po %O %A %B
And enable its use by defining proper attributes in given repository (eg. in
This merge driver assumes the changes in POT files always are done in the branch we’re trying to merge.
Changed in version 2.9: This merge driver is now automatically installed for all Weblate internal repositories.
Avoiding merge conflicts¶
To avoid merge conflicts you should control when to update translation files in upstream repository to avoid Weblate having changes on same file.
You can achieve this using Weblate’s Web API to force Weblate push all pending changes and lock translation while you are doing changes on your side.
The script for doing updates can look like:
# 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 same repository, you need to lock them all separately:
wlc lock foo/bar wlc lock foo/baz wlc lock foo/baj
Automatically receiving changes from GitHub¶
Weblate comes with native support for GitHub.
If you are using Hosted Weblate the recommended approach is to install Hosted Weblate app, that way you will get correct setup without much configuring. In future it will be used for pushing changes back as well (that’s why the write permission is requested), but it’s not yet implemented.
To receive notifications on every push to GitHub repository, you just need to add Weblate Webhook in the repository settings (Webhooks) as shown on the image below:
For the payload URL append
/hooks/github/ to your Weblate URL, for example
for Hosted Weblate service this is
You can leave other values on the default settings (Weblate can handle both content types and consumes just the push event).
Automatically receiving changes from Bitbucket¶
Weblate has support for Bitbucket webhooks, all you need to do is add a webhook
which triggers on repository push with destination to
on your Weblate installation (for example
Automatically receiving changes from GitLab¶
Weblate has support for GitLab hooks, all you need to do is add project web hook
with destination to
/hooks/gitlab/ URL on your Weblate installation
Automatically receiving changes from Pagure¶
New in version 3.3.
Weblate has support for Pagure hooks, all you need to do is add project web hook
with destination to
/hooks/pagure/ URL on your Weblate installation (for
https://hosted.weblate.org/hooks/pagure/). This can be done in
Activate Web-hooks under Project options:
Each project can have a push URL configured and in that case Weblate offers a button in the web interface to push changes to the remote repository. Weblate can be also configured to automatically push changes on every commit.
If you are using SSH to push, you will need to have a key without a passphrase (or use ssh-agent for Django) and the remote server needs to be verified by you via the admin interface first, otherwise pushing will fail.
The push options differ based on the Version control integration used, please check that chapter for more details.
You can also enable the automatic pushing of changes on commit, this can be done in Component configuration.
Pushing changes from Hosted Weblate¶
For Hosted Weblate there is a dedicated push user registered on GitHub, Bitbucket and GitLab (with username weblate and named Weblate push user). You need to add this user as a collaborator and give him permissions to push to your repository. Let us know when you’ve done so and we will enable pushing changes from Hosted Weblate for you.
Merge or rebase¶
By default, Weblate merges the upstream repository into its own. This is the safest way in case you also access the underlying repository by other means. In case you don’t need this, you can enable rebasing of changes on upstream, which will produce history with fewer merge commits.
Rebasing can cause you troubles in case of complicated merges, so carefully consider whether or not you want to enable them.
Interacting with others¶
Weblate makes it easy to interact with others using its API.
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, eg. for merge (this is by default allowed for Managers group, see Access control).
The changes are in this mode committed once any of following conditions is fulfilled:
- somebody else changes already changed string
- a merge from upstream occurs
- import of translation happens
- mass state change is performed
- search and replace is executed
- explicit commit is requested