There is infrastructure in place so that your translation closely followsdevelopment. 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 developmentwith 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).
Hint
Upstream code hosting is not necessary, you can use Weblate withLocal files where there is only the repository inside Weblate.
Updating repositories¶
You should set up some way of updating backend repositories from theirsource.
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
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
--allto update all)
Whenever Weblate updates the repository, the post-update addons will betriggered, see Add-ons.
Avoiding merge conflicts¶
The merge conflicts from Weblate arise when same file was changed both inWeblate and outside it. There are two approaches to deal with that - avoidedits outside Weblate or integrate Weblate into your updating process, so thatit flushes changes prior to updating the files outside Weblate.
The first approach is easy with monolingual files — you can add new stringswithin Weblate and leave whole editing of the files there. For bilingual files,there is usually some kind of message extraction process to generatetranslatable files from the source code. In some cases this can be split intotwo parts - one for the extraction generates template (for example gettext POTis generated using xgettext) and then further process merges it intoactual translations (the gettext PO files are updated usingmsgmerge). You can perform the second step within Weblate and itwill ensure that all pending changes are included prior to this operation.
The second approach can be achieved by using Weblate’s REST API to force Weblate topush all pending changes and lock the translation while you are doing changeson your side.
The script for doing updates can look like this:
# Lock Weblate translationwlc lock# Push changes from Weblate to upstream repositorywlc push# Pull changes from upstream repository to your local copygit pull# Update translation files, this example is for Django./manage.py makemessages --keep-pot -agit commit -m 'Locale updates' -- locale# Push changes to upstream repositorygit push# Tell Weblate to pull changes (not needed if Weblate follows your repo# automatically)wlc pull# Unlock translationswlc unlock
If you have multiple components sharing same repository, you need to lock themall separately:
wlc lock foo/barwlc lock foo/bazwlc lock foo/baj
Note
The example uses Weblate Client, which needs configuration (API keys) to beable to control Weblate remotely. You can also achieve this using any HTTPclient instead of wlc, e.g. curl, see Weblate’s REST API.
Avoiding merge conflicts on Weblate originated changes¶
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 aresquashing commits outside of Weblate (for example when merging a pull request).
The reason for merge conflicts is different in this case - there are changes inWeblate which happened after you merged Weblate commits. This typically happensif merging is not automated and waits for days or weeks for a human to reviewthem. Git is then sometimes no longer able to identify upstream changes asmatching the Weblate ones and refuses to perform a rebase.
To approach this, you either need to minimize amount of pending changes inWeblate when you merge a pull request, or avoid the conflicts completely by notsquashing 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 theWeblate app, that way you will get thecorrect setup without having to set much up. It can also be used for pushingchanges back.
To receive notifications on every push to a GitHub repository,add the 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 examplefor the Hosted Weblate service, this is https://hosted.weblate.org/hooks/github/.
You can leave other values at default settings (Weblate can handle bothcontent 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 webhookwhich triggers upon repository push, with destination to /hooks/bitbucket/ URLon your Weblate installation (for examplehttps://hosted.weblate.org/hooks/bitbucket/).
See also
POST /hooks/bitbucket/, Accessing repositories from Hosted Weblate
Automatically receiving changes from GitLab¶
Weblate has support for GitLab hooks, add a project webhookwith destination to /hooks/gitlab/ URL on your Weblate installation(for example https://hosted.weblate.org/hooks/gitlab/).
See also
POST /hooks/gitlab/, Accessing repositories from Hosted Weblate
Automatically receiving changes from Pagure¶
Weblate has support for Pagure hooks, add a webhookwith destination to /hooks/pagure/ URL on your Weblate installation (forexample https://hosted.weblate.org/hooks/pagure/). This can be done inActivate 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 forCode pushed event with destination to /hooks/azure/ URL on yourWeblate installation (for example https://hosted.weblate.org/hooks/azure/).This can be done in Service hooks under Projectsettings.
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 forPush events event with destination to /hooks/gitea/ URL on yourWeblate installation (for example https://hosted.weblate.org/hooks/gitea/).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 Gitee Repos¶
Weblate has support for Gitee webhooks, add a WebHook forPush event with destination to /hooks/gitee/ URL on yourWeblate installation (for example https://hosted.weblate.org/hooks/gitee/).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 improveperformance when merging changes later. You can optionally turn this into doingnightly merges as well, by enabling AUTO_UPDATE.
Pushing changes from Weblate¶
Each translation component can have a push URL set up (seeRepository push URL), and in that case Weblate will be able to push change tothe remote repository. Weblate can be also be configured to automatically pushchanges on every commit (this is default, see Push on commit).If you do not want changes to be pushed automatically, you can do that manuallyunder 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 forGitHub pull requests, GitLab merge requests, Gitea pull requests, Pagure merge requests,Azure DevOps pull requests pull requests or Gerrit reviews, you can activate these bychoosing 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, and Azure DevOps:
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 [1] | Branch name |
GitLab merge request from fork | GitLab merge requests | empty | empty |
GitLab merge request from branch | GitLab merge requests | SSH URL [1] | Branch name |
Gitea merge request from fork | Gitea pull requests | empty | empty |
Gitea merge request from branch | Gitea pull requests | SSH URL [1] | Branch name |
Pagure merge request from fork | Pagure merge requests | empty | empty |
Pagure merge request from branch | Pagure merge requests | SSH URL [1] | 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 [1] | Branch name |
Note
You can also enable automatic pushing of changes after Weblate commits, this can be done inPush on commit.
See also
See Accessing repositories for setting up SSH keys, and Lazy commits forinfo about when Weblate decides to commit changes.
Protected branches¶
If you are using Weblate on protected branch, you can configure it to use pullrequests and perform actual review on the translations (what might beproblematic for languages you do not know). An alternative approach is to waivethis 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 onecommit if possible. This greatly reduces the number of commits, however youmight need to explicitly tell it to do the commits in case you want to get theVCS repository in sync, e.g. for merge (this is by default allowed for the Managersgroup, see List of privileges).
The changes in this mode are committed once any of the following conditions arefulfilled:
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 componentsyou will still see lot of commits. You might utilizeSquash Git commits add-on in that case.
If you want to commit changes more frequently and without checking of age, youcan schedule a regular task to perform a commit. This can be done usingPeriodic Tasks in The Django admin interface. First create desiredInterval (for example 120 seconds). Then add new periodic task andchoose 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 isAdd-ons. Consult Executing scripts from add-on for info on how to executeexternal scripts through add-ons.
Keeping translations same across components¶
Once you have multiple translation components, you might want to ensure thatthe same strings have same translation. This can be achieved at several levels.
Translation propagation¶
With Allow translation propagation enabled (what is the default, seeComponent configuration), all new translations are automatically done in allcomponents with matching strings. Such translations are properly credited tocurrently translating user in all components.
Note
The translation propagation requires the key to be match for monolingualtranslation formats, so keep that in mind when creating translation keys.
Consistency check¶
The Inconsistent check fires whenever the strings are different.You can utilize this to review such differences manually and choose the righttranslation.
Automatic translation¶
Automatic translation based on different components can be way to synchronizethe translations across components. You can either trigger it manually (seeAutomatic translation) or make it run automatically on repository updateusing add-on (see Automatic translation).
 Program - Payability)