Continuous translation

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:

  1. Developers make some changes and push them to the VCS repository.
  2. 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?).
  3. Weblate pulls changes from the VCS repository, see Updating repositories.
  4. Once Weblate detects changes in translations, translators will be notified based on their subscription settings.
  5. Translators make translations using Weblate web interface.
  6. 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).

digraph translations { "Developers" [shape=box, fillcolor=lightgreen, style=filled]; "Translators" [shape=box, fillcolor=lightgreen, style=filled]; "Developers" -> "VCS repository" [label=" 1. Push "]; "VCS repository" -> "VCS repository" [label=" 2. Updating translations ", style=dotted]; "VCS repository" -> "Weblate" [label=" 3. Pull "]; "Weblate" -> "Translators" [label=" 4. Notification "]; "Translators" -> "Weblate" [label=" 5. Translate "]; "Weblate" -> "VCS repository" [label=" 6. Push "]; }

Updating repositories

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 .gitconfig:

[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 .git/info/attributes):

*.po merge=merge-gettext-po

Note

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

wlc lock foo/bar
wlc lock foo/baz
wlc lock foo/baj

Note

The example uses Weblate Client, which will need configuration (API keys) to be able to control Weblate remotely. You can also achieve this using any HTTP client instead of wlc, eg. curl, see Weblate’s Web API.

Automatically receiving changes from GitHub

Weblate comes with native support for GitHub. 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:

../_images/github-settings.png

For the payload URL append /hooks/github/ to your Weblate URL, for example for Hosted Weblate service this is https://hosted.weblate.org/hooks/github/.

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 /hooks/bitbucket/ URL on your Weblate installation (for example https://hosted.weblate.org/hooks/bitbucket/).

../_images/bitbucket-settings.png

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 (for example https://hosted.weblate.org/hooks/gitlab/).

Pushing changes

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.

Note

You can also enable the automatic pushing of changes on commit, this can be done in Component configuration.

See also

See Accessing repositories for setting up SSH keys and Lazy commits for information about when Weblate decides to commit changes.

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

Note

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.

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, 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
  • translation for a language is completed
  • explicit commit is requested

You can also additionally set a cron job to commit pending changes after some delay, see commit_pending and Running maintenance tasks.

Processing repository with scripts

The way to customize how Weblate interacts with the repository are Addons. See Executing scripts from addon for infomrmation how to execute external scripts through addons.